[
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)
