cassandra-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sylvain Lebresne (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
Date Mon, 13 Jun 2016 14:48:21 GMT

    [ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15327521#comment-15327521
] 

Sylvain Lebresne commented on CASSANDRA-8700:
---------------------------------------------

I had a look at what could be good options here. I'm sure I've missed some but some reasonable
(as in, good without being too complex) options seems to be:
* [textile|http://redcloth.org/textile]: I mention it _only_  because it's currently used
for the CQL doc, but having written a fair amount of said doc, I hate it and am against continuing
to use it (the top reason for my hatred being that new lines in the input are mirorred in
the output which is just extremely annoying).
* [sphinx|http://www.sphinx-doc.org/]: Was mentioned by a few people already and it is a great
option. It's reasonably simple while being fairly complete and maintained. The main downside
seems to be that reStructuredText is not always as pleasant to work with than say markdown
(probably debatable but internet seems to generally agree on that). That said, reStructuredText
is not that bad either and it's arguably more capable than markdown for some things. Sphinx
also has a bunch of extension, and while I'm not sure we'll need that much, some might come
in handy someday.
* [MkDocs|http://www.mkdocs.org/]: A nice option in that it's simple but still produce decently
looking docs (with navigation and search), and it uses markdown, which has the advantage of
being more well known. It is however arguably less flexible than sphinx: in particular it
doesn't seem to be able to easily produce pdfs, which would be nice to have.
* [asciidoc|http://asciidoc.org/]: Haven't looked at it _that_ close but it's definitively
capable (it's use by hbase for [their book|https://hbase.apache.org/book.html] in particular,
and it doesn't look bad) but sphinx seems to have strictly more advantages.
* [mdBook|http://azerupi.github.io/mdBook/]: uses mardown so not too disimilar to MkDocs,
but slightly less capable (doesn't probide search for instance). Also made for the rust book
so requires to install rust which is inconvenient (since we have no dependency on rust currently).
* There is also a bunch of tools to convert from one markup languages to html, amongst which
the more general is probably [pandoc|http://pandoc.org/], but those are probably a bit too
crude.

Anyway, I'm happy to check other options and debate which is best but it seems that sphinx
(which has had some vote already) is a pretty good choice and so I've started setting it up
(I'll try to commit a first WIP version of the outline plus the sections attached above tomorrow).
If we decide that we prefer another option in the coming days, that's fine, I'll just convert
the files (which is pretty simple with pandoc, so if you've already written something in markdown,
feel free to attach it that way, I'll convert).


> replace the wiki with docs in the git repo
> ------------------------------------------
>
>                 Key: CASSANDRA-8700
>                 URL: https://issues.apache.org/jira/browse/CASSANDRA-8700
>             Project: Cassandra
>          Issue Type: Improvement
>          Components: Documentation and Website
>            Reporter: Jon Haddad
>            Assignee: Sylvain Lebresne
>            Priority: Minor
>         Attachments: TombstonesAndGcGrace.md, bloom_filters.md, compression.md, drivers_list.md,
hardware.md, installation.md
>
>
> The wiki as it stands is pretty terrible.  It takes several minutes to apply a single
update, and as a result, it's almost never updated.  The information there has very little
context as to what version it applies to.  Most people I've talked to that try to use the
information they find there find it is more confusing than helpful.
> I'd like to propose that instead of using the wiki, the doc directory in the cassandra
repo be used for docs (already used for CQL3 spec) in a format that can be built to a variety
of output formats like HTML / epub / etc.  I won't start the bikeshedding on which markup
format is preferable - but there are several options that can work perfectly fine.  I've personally
use sphinx w/ restructured text, and markdown.  Both can build easily and as an added bonus
be pushed to readthedocs (or something similar) automatically.  For an example, see cqlengine's
documentation, which I think is already significantly better than the wiki: http://cqlengine.readthedocs.org/en/latest/
> In addition to being overall easier to maintain, putting the documentation in the git
repo adds context, since it evolves with the versions of Cassandra.
> If the wiki were kept even remotely up to date, I wouldn't bother with this, but not
having at least some basic documentation in the repo, or anywhere associated with the project,
is frustrating.
> For reference, the last 3 updates were:
> 1/15/15 - updating committers list
> 1/08/15 - updating contributers and how to contribute
> 12/16/14 - added a link to CQL docs from wiki frontpage (by me)



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

Mime
View raw message