cassandra-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sylvain Lebresne (JIRA)" <>
Subject [jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
Date Tue, 14 Jun 2016 14:32:01 GMT


Sylvain Lebresne commented on CASSANDRA-8700:

So, progress update: I've pushed a WIP branch [here|]
with a first version of the doc. It contains the outline from the google doc document Jonathan
mentioned above with the few sections attached here (by [~Stefania], [~jjirsa] and [~rspitzer])
filled. I've also put the CQL doc but the conversion from textile didn't went too well so
it's pretty broken right now and I'm going to work on fixing that next.

As said above, it uses sphinx (and the sphinx_rtd_theme; if you have neither, it's a {{pip
install sphinx sphinx_rtd_theme}} away) and I've added a {{gen-doc}} ant target to build the
html (but it actually just delegates to the {{Makefile}} that sphinx provides, which can be
used to build other formats like pdf, epub, ...). There is a new {{}} file in {{doc/}}
that explains all that.

Currently, the static html is put in a {{doc/build/}} directory, and once we're ready to put
that online, we'll probably have to copy that manually since the website is not in git. On
that topic, would be nice to see if we can get that to change, moving the site in git so we
can automate publishing a bit more easily.

Another point worth mentioning is that the branch is against trunk and that I used the CQL
doc from there. So if we want to commit to earlier branch, we'll theoretically have to change
the CQL doc used (and as said above, it's a bit painful to migrate). Alternatively, we could
commit in trunk only and say that for earlier versions, user should check the CQL doc changelog
to figure out if a given CQL feature is available in their version.

Anyway, I guess the most important thing missing is content: most of it is currently TODO.
So let's try to continue focusing on filling the blanks. You are, btw, welcome to create pull-request
against my branch above for that (but I'm also still fine with just attaching particular chapters
here as as been done so far).

And for those that are curious how it currently looks like and can't be bothered to compile
it locally, I've pushed the current version temporarily [here|]
(again, the CQL part is broken, working on it).

> replace the wiki with docs in the git repo
> ------------------------------------------
>                 Key: CASSANDRA-8700
>                 URL:
>             Project: Cassandra
>          Issue Type: Improvement
>          Components: Documentation and Website
>            Reporter: Jon Haddad
>            Assignee: Sylvain Lebresne
>            Priority: Minor
>         Attachments:,,,,,
> 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:
> 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

View raw message