[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[ https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16535293#comment-16535293 ] Patrick Bannister commented on CASSANDRA-13907: --- How are things going with versioned documentation? Over on CASSANDRA-13047 we're looking at updating cqlsh to point to online help; currently it points to dead links for an older version of the docs. We could easily update cqlsh to point to the currently available online help, but depending on your expected timeline, it might make more sense to hold out for versioned docs. > Versioned documentation on cassandra.apache.org > --- > > Key: CASSANDRA-13907 > URL: https://issues.apache.org/jira/browse/CASSANDRA-13907 > Project: Cassandra > Issue Type: Improvement > Components: Documentation and Website >Reporter: Murukesh Mohanan >Priority: Minor > > Services like https://readthedocs.org and http://www.javadoc.io/ make it easy > to browse the documentation for a particular version or commit of various > open source projects. It would be nice to be able to browse the docs for a > particular release on http://cassandra.apache.org/doc/. > Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/. -- This message was sent by Atlassian JIRA (v7.6.3#76005) - To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[ https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16211365#comment-16211365 ] Jon Haddad commented on CASSANDRA-13907: I had a discussion with [~mshuler] at NGCC regarding taking over updating the docs, and I've dropped the ball, my bad on that. As I stated above, I think it would be fantastic to have versioned docs, but I believe we should figure out a few things first since moving on them to early will create a massive headache in the long run. Here's what I think is the most efficient, least foot shooting approach to eventually get versioned docs: 1. I'll take over the job of pushing documentation for trunk 2. We get docs in a really solid state for 4.0. Completely comprehensive. 3. We evaluate if the current method of writing docs is the appropriate system. I've recently done a lot of work with [Hugo|https://gohugo.io/] to write the docs for [Reaper|http://cassandra-reaper.io/docs/| and it's a lot easier to write and generate docs. The whole Jekyl + sphinx thing is obviously a pain point, I'd like to address this. 4. Once we're finally in good shape with documentation, we aim to make hosting multiple versions a regular thing. > Versioned documentation on cassandra.apache.org > --- > > Key: CASSANDRA-13907 > URL: https://issues.apache.org/jira/browse/CASSANDRA-13907 > Project: Cassandra > Issue Type: Improvement > Components: Documentation and Website >Reporter: Murukesh Mohanan >Priority: Minor > > Services like https://readthedocs.org and http://www.javadoc.io/ make it easy > to browse the documentation for a particular version or commit of various > open source projects. It would be nice to be able to browse the docs for a > particular release on http://cassandra.apache.org/doc/. > Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/. -- This message was sent by Atlassian JIRA (v6.4.14#64029) - To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[
https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16211161#comment-16211161
]
Michael Shuler commented on CASSANDRA-13907:
I just wish to pass along my experiences with updating the website for the last
year or so.
- the smallest of edits (ie. new version number) generally end up with
sometimes very large unrelated HTML diff
- jekyll versions matter, which is being worked on and has had some notes added
to the README
- even with the "correct" jekyll version, building on different OS results in
different HTML tags
- some component of the build process doesn't seem understand existing
files/dirs
- code blocks are not copy & paste friendly, and I end up hand editing HTML to
remove line numbers
- many times I use the build to see what will be changed when markdown files
are updated (along with massive unintended changes), revert everything, then
hand edit
{noformat}
svn revert --recursive .
svn revert --recursive .
svn revert publish/.htaccess
svn revert --recursive publish/doc/cql3
svn revert publish/community/index.html
svn revert publish/download/index.html
svn revert --recursive .
svn revert --recursive .
svn revert --recursive ../
svn revert --recursive .
svn revert --recursive .
svn revert --recursive .
svn revert --recursive .
svn revert --recursive .
svn revert --recursive ../
svn revert --recursive ../
svn revert --recursive publish/doc/3.7
svn revert --recursive publish/doc/cql3
svn revert --recursive publish/.htaccess
svn revert --recursive .
svn revert --recursive publish/doc/3.7
svn revert publish/.htaccess
svn revert --recursive publish/doc/cql3
svn revert --recursive publish/doc/3.7
svn revert publish/.htaccess
svn revert --recursive publish/doc/cql3
svn revert --recursive .
svn revert --recursive publish/doc/3.7
svn revert publish/.htaccess
svn revert --recursive publish/doc/cql3
svn revert --recursive ../
svn revert --recursive publish/.htaccess
svn revert --recursive publish/doc/3.7
svn revert --recursive publish/doc/cql3
svn revert --recursive publish/.htaccess publish/doc/3.7 publish/doc/cql3
svn revert --recursive publish/.htaccess publish/doc/3.7 publish/doc/cql3
svn revert --recursive .
svn revert --recursive publish/.htaccess publish/doc/3.7 publish/doc/cql3
svn revert --recursive .
svn revert --recursive .
svn revert --recursive publish/.htaccess publish/doc/3.7 publish/doc/cql3
svn revert --recursive publish/.htaccess publish/doc/cql3
svn revert --recursive publish/
svn revert --recursive publish/
svn revert --recursive src/doc/
svn revert --recursive publish/.htaccess publish/doc/3.7 publish/doc/cql3
svn revert publish/index.html
svn revert publish/community/index.html
svn revert --recursive publish/.htaccess publish/doc/3.7 publish/doc/cql3
svn revert publish/community/index.html
svn revert publish/index.html
svn revert --recursive publish/.htaccess publish/doc/3.7 publish/doc/cql3
svn revert publish/community/index.html
svn revert publish/index.html
svn revert --recursive publish/.htaccess publish/doc/3.7 publish/doc/cql3
svn revert publish/community/index.html
svn revert publish/index.html
svn revert --recursive publish/.htaccess publish/doc/3.7 publish/doc/cql3
svn revert publish/community/index.html
svn revert publish/index.html
svn revert --recursive .
svn revert --recursive publish/doc/cql3 publish/.htaccess
svn revert --recursive site/
svn revert --recursive publish/.htaccess publish/doc/cql3 publish/doc/3.7
svn revert --recursive .
svn revert --recursive .
svn revert --recursive .
svn revert --recursive .
svn revert --recursive .
svn revert --recursive publish/.htaccess publish/doc/cql3 publish/doc/3.7
svn revert publish/community/index.html publish/download/index.html
svn revert --recursive .
svn revert --recursive .
svn revert --recursive .
svn revert --recursive publish/.htaccess publish/doc/cql3
svn revert publish/community/index.html
svn revert publish/.htaccess
svn revert --recursive publish/doc/cql3
svn revert publish/.htaccess publish/doc/cql3
svn revert --recursive publish/.htaccess publish/doc/cql3
svn revert src/download.md publish/download/index.html
svn revert --recursive publish/.htaccess publish/doc/cql3
svn revert --recursive publish/.htaccess publish/doc/cql3
svn revert --recursive publish/.htaccess publish/doc/cql3
svn revert --recursive publish/.htaccess publish/doc/cql3
{noformat}
> Versioned documentation on cassandra.apache.org
> ---
>
> Key: CASSANDRA-13907
> URL: https://issues.apache.org/jira/browse/CASSANDRA-13907
> Project: Cassandra
> Issue Type: Improvement
> Components: Documentation and Website
>Reporter: Murukesh Mohanan
>Priority: Minor
>
> Services like https://readthedocs.org and http://www.javadoc.io/ make it easy
> to browse the documentation for a particular version or
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[ https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16210929#comment-16210929 ] Murukesh Mohanan commented on CASSANDRA-13907: -- Nothing further on labeling the versions from me, then. I'd rather have multiple versions supported than bicker about what to call them. Thanks for the link to the source. Reading the README, I can appreciate why Michael might generate just the trunk and leave it alone. Integrating Jekyll with a non-Jekyll source is a PITA. Having a consistent theme and structure to the docs and the main Cassandra site is important, and that's probably why this devolved to the way it is now. As it always does, it looks like this will take more effort than I originally thought it would. :) In the meantime, I'll try to set it up so that the POC is automatically updated so that versioned docs are available somewhere. > Versioned documentation on cassandra.apache.org > --- > > Key: CASSANDRA-13907 > URL: https://issues.apache.org/jira/browse/CASSANDRA-13907 > Project: Cassandra > Issue Type: Improvement > Components: Documentation and Website >Reporter: Murukesh Mohanan >Priority: Minor > > Services like https://readthedocs.org and http://www.javadoc.io/ make it easy > to browse the documentation for a particular version or commit of various > open source projects. It would be nice to be able to browse the docs for a > particular release on http://cassandra.apache.org/doc/. > Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/. -- This message was sent by Atlassian JIRA (v6.4.14#64029) - To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[
https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16210865#comment-16210865
]
Sylvain Lebresne commented on CASSANDRA-13907:
--
bq. Are the scripts for the website open?
The whole site is at https://svn.apache.org/repos/asf/cassandra/site/, the
scripts I'm referring to is basically the {{Makefile}} under {{src/}}.
bq. How about something like the Debian system
I don't think there is any other system to copy here. The supported
branch/versions at any given are the one at
http://cassandra.apache.org/download/ and that should always be up to date, so
that's version we should have doc for. But as to label them with
old-stable/stable, it's a can of worm: we have had debate over this many many
times and we can't seem to agree on what to call stable and what not to, so I
strongly suggest avoiding re-opening that debate if you want any quick
resolution to this. I think using the "branch" for naming (so, at the current
time {{doc/2.1}}, {{doc/2.2}}, {{doc/3.0}} and {{doc/3.11}}) and a {{latest}}
pointer would be good enough for now and I'd suggest sticking to that.
bq. Is there something I can do to help with this?
I'm sure the aforementioned {{Makefile}} could be improved to make the
enforcement of a scheme as described above easier and less error prone and I'm
sure help for that would be appreciated. But as to making sure this stay
properly updated upon new releases, that's largely up to whomever is doing the
releases (so [~mshuler] as of now).
> Versioned documentation on cassandra.apache.org
> ---
>
> Key: CASSANDRA-13907
> URL: https://issues.apache.org/jira/browse/CASSANDRA-13907
> Project: Cassandra
> Issue Type: Improvement
> Components: Documentation and Website
>Reporter: Murukesh Mohanan
>Priority: Minor
>
> Services like https://readthedocs.org and http://www.javadoc.io/ make it easy
> to browse the documentation for a particular version or commit of various
> open source projects. It would be nice to be able to browse the docs for a
> particular release on http://cassandra.apache.org/doc/.
> Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
-
To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[
https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16210844#comment-16210844
]
Murukesh Mohanan commented on CASSANDRA-13907:
--
Having all versions would be impractical (I think the services which do
per-commit docs generate them on-demand, but I'm not sure). Since {{make html}}
only worked for 5 tags, I just added them all to my site.
How about something like the Debian system: old-stable (2.X), stable (3.0),
latest (3.11), and trunk (rolling, updated regularly, maybe once a week)? If
links like {{/stable}}, {{/latest}} can be provided, it would be even more
convenient.
Is there something I can do to help with this? Are the scripts for the website
open?
> Versioned documentation on cassandra.apache.org
> ---
>
> Key: CASSANDRA-13907
> URL: https://issues.apache.org/jira/browse/CASSANDRA-13907
> Project: Cassandra
> Issue Type: Improvement
> Components: Documentation and Website
>Reporter: Murukesh Mohanan
>Priority: Minor
>
> Services like https://readthedocs.org and http://www.javadoc.io/ make it easy
> to browse the documentation for a particular version or commit of various
> open source projects. It would be nice to be able to browse the docs for a
> particular release on http://cassandra.apache.org/doc/.
> Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
-
To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[
https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16210820#comment-16210820
]
Sylvain Lebresne commented on CASSANDRA-13907:
--
For what it's worth, the current code to generate the doc for the web-site
already has everything need to create per-version code. The intent was to have
per-version doc at {{doc/}}, with {{doc/latest}} always pointing to
the latest version. But this hasn't been done properly when the doc has been
updated, and in fact the only version currently up is that of 4.0, which isn't
even released so it's obviously completely wrong. So don't think we need much
new code here, just better discipline in updating the web site ([~mshuler]:
pinging you in particular since I believe you've been the one doing such
updates for new release). Could be the existing scripts could be improved to
make it easier though.
With all this being said, I'm not 100% certain the ASF would be fine with us
keeping *all* versions (and thus an always increasing number of them) online
moving forward. It might be we have to stick to one doc by "major" branch, so
today that would be {{doc/3.0/}} and {{doc/3.11}} with {{doc/latest}} pointing
to the latter.
> Versioned documentation on cassandra.apache.org
> ---
>
> Key: CASSANDRA-13907
> URL: https://issues.apache.org/jira/browse/CASSANDRA-13907
> Project: Cassandra
> Issue Type: Improvement
> Components: Documentation and Website
>Reporter: Murukesh Mohanan
>Priority: Minor
>
> Services like https://readthedocs.org and http://www.javadoc.io/ make it easy
> to browse the documentation for a particular version or commit of various
> open source projects. It would be nice to be able to browse the docs for a
> particular release on http://cassandra.apache.org/doc/.
> Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
-
To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[
https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16209566#comment-16209566
]
Murukesh Mohanan commented on CASSANDRA-13907:
--
As a POC, I created a GitHub Pages site:
https://murukeshm.github.io/cassandra/3.9/ (check the dropdown near the
copyright notice at the bottom of the page). The commands I used to create them
are in https://github.com/murukeshm/cassandra/blob/gh-pages/gen.sh It's a bit
hacky: inserting a {{}} for versions after the HTML docs have been
generated, and I haven't created a central index page yet, but it can serve as
a baseline.
> Versioned documentation on cassandra.apache.org
> ---
>
> Key: CASSANDRA-13907
> URL: https://issues.apache.org/jira/browse/CASSANDRA-13907
> Project: Cassandra
> Issue Type: Improvement
> Components: Documentation and Website
>Reporter: Murukesh Mohanan
>Priority: Minor
>
> Services like https://readthedocs.org and http://www.javadoc.io/ make it easy
> to browse the documentation for a particular version or commit of various
> open source projects. It would be nice to be able to browse the docs for a
> particular release on http://cassandra.apache.org/doc/.
> Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
-
To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[ https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16209257#comment-16209257 ] Jon Haddad commented on CASSANDRA-13907: No arguments here. I agree, it would be nice to have eventually. > Versioned documentation on cassandra.apache.org > --- > > Key: CASSANDRA-13907 > URL: https://issues.apache.org/jira/browse/CASSANDRA-13907 > Project: Cassandra > Issue Type: Improvement > Components: Documentation and Website >Reporter: Murukesh Mohanan >Priority: Minor > > Services like https://readthedocs.org and http://www.javadoc.io/ make it easy > to browse the documentation for a particular version or commit of various > open source projects. It would be nice to be able to browse the docs for a > particular release on http://cassandra.apache.org/doc/. > Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/. -- This message was sent by Atlassian JIRA (v6.4.14#64029) - To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[ https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16209254#comment-16209254 ] Murukesh Mohanan commented on CASSANDRA-13907: -- I do, that's why I think this is possible in the first place. Being able to read the docs without having C* installed, or of a different version than the one you have, is extremely convenient. Think of the versioned manpage browsing sites ([Ubuntu|http://manpages.ubuntu.com], or [Debian|https://manpages.debian.org] or the absolutely fantastic [FreeBSD manpage browser|https://freebsd.org/cgi/man.cgi]), or what's probably the best documentation site of a software project, [the Python docs|https://docs.python.org/] (which are canonical, feature all supported versions, support multiple languages, has excellent search, etc.). Having some documentation online is good ... but given that we have a release every few months or so, the online docs will quickly outpace anything that people will likely have installed (and are, therefore, using). It's not essential, but it's nice to have. > Versioned documentation on cassandra.apache.org > --- > > Key: CASSANDRA-13907 > URL: https://issues.apache.org/jira/browse/CASSANDRA-13907 > Project: Cassandra > Issue Type: Improvement > Components: Documentation and Website >Reporter: Murukesh Mohanan >Priority: Minor > > Services like https://readthedocs.org and http://www.javadoc.io/ make it easy > to browse the documentation for a particular version or commit of various > open source projects. It would be nice to be able to browse the docs for a > particular release on http://cassandra.apache.org/doc/. > Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/. -- This message was sent by Atlassian JIRA (v6.4.14#64029) - To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-13907) Versioned documentation on cassandra.apache.org
[ https://issues.apache.org/jira/browse/CASSANDRA-13907?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16209194#comment-16209194 ] Jon Haddad commented on CASSANDRA-13907: Not sure if you're aware of this, but the docs ship with Cassandra itself. > Versioned documentation on cassandra.apache.org > --- > > Key: CASSANDRA-13907 > URL: https://issues.apache.org/jira/browse/CASSANDRA-13907 > Project: Cassandra > Issue Type: Improvement > Components: Documentation and Website >Reporter: Murukesh Mohanan >Priority: Minor > > Services like https://readthedocs.org and http://www.javadoc.io/ make it easy > to browse the documentation for a particular version or commit of various > open source projects. It would be nice to be able to browse the docs for a > particular release on http://cassandra.apache.org/doc/. > Currently it seems only CQL has this at http://cassandra.apache.org/doc/old/. -- This message was sent by Atlassian JIRA (v6.4.14#64029) - To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org For additional commands, e-mail: commits-h...@cassandra.apache.org
