Murukesh is correct on a very useable, pretty standard process of multi-versioned docs.
I’ll put my thoughts in a JIRA epic tonight. I’ll be a multi-phase process. Also correct in that I’d like us to move to Hugo for the site, I’d like us to have a unified system between the site & the docs, and hugo has been excellent. We run the reaper site & docs off hugo, it works well. We just don’t do multi-versions (because we don’t support multiple): https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs <https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs>. Jon > On Mar 15, 2018, at 8:57 AM, Murukesh Mohanan <murukesh.moha...@gmail.com> > wrote: > > On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman <kenbrot...@yahoo.com.invalid > <mailto:kenbrot...@yahoo.com.invalid>> > wrote: > >> Help me out here. I could have had a website with support for more than >> one version done several different ways by now. >> >> A website with several versions of documentation is going to have >> sub-directories for each version of documentation obviously. I've offered >> to create those sub-directories under the "doc" folder of the current >> repository; and I've offered to move the online documentation to a separate >> repository and have the sub-directories there. Both were shot down. Is >> there a third way? If so please just spill the beans. >> > > There is. Note that the website is an independent repository. So to host > docs for multiple versions, only the website's repository (or rather, the > final built contents) needs multiple directories. You can just checkout > each branch or tag, generate the docs, make a directory for that branch or > tag in the website repo, and copy the generated docs there with appropriate > modifications. > > I do this on a smaller scale using GitHub Pages (repo: > https://github.com/murukeshm/cassandra > <https://github.com/murukeshm/cassandra> site: > https://murukeshm.github.io/cassandra/ > <https://murukeshm.github.io/cassandra/> > <https://murukeshm.github.io/cassandra/3.11.1/ > <https://murukeshm.github.io/cassandra/3.11.1/>> ). The method is a bit > hacky as I noted in CASSANDRA-13907. A daily cronjobs updated the repo if > docs are updated. 3.9+ versions are available. > > > > >> Also, no offense to anyone at Sphinx but for a project our size it's not >> suitable. We need to move off it now. It's a problem. >> >> Can we go past this and on to the documenting! Please help resolve this. >> >> How are we going to: >> Make the submission of code changes include required changes to >> documentation including the online documentation? >> Allow, encourage the online documentation to publish multiple versions of >> documentation concurrently including all officially supported versions? > > > Only on this point: we'll need to start by improving the website build > process. Michael's comment on 13907 ( > https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentId=16211365&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16211365 > > <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentId=16211365&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16211365> > ) > shows it's a painful, fiddly process. That seems to be the main blocker. I > think Jon has shown interest in moving to Hugo from the current Jekyll > setup. > > > >> Move our project onto a more suitable program than Sphinx for our needs? >> >> Kenneth Brotman >> >> -----Original Message----- >> From: Eric Evans [mailto:john.eric.ev...@gmail.com] >> Sent: Thursday, March 15, 2018 7:50 AM >> To: dev@cassandra.apache.org >> Subject: Re: A JIRA proposing a seperate repository for the online >> documentation >> >> On Thu, Mar 15, 2018 at 4:58 AM, Rahul Singh <rahul.xavier.si...@gmail.com> >> wrote: >>> >>> I don’t understand why it’s so complicated. In tree docs are as good as >> any. All the old docs are there in the version control system. >>> >>> All we need to is a) generate docs for old versions b) improve user >> experience on the site by having it clearly laid out what is latest vs. old >> docs and c) have some semblance of a search maybe using something like >> Algolia or whatever. >> >> This. >> >> Keeping the docs in-tree is a huge win, because they can move in lock-step >> with changes occurring in that branch/version. I don't think we've been >> enforcing this, but code-changes that alter documented behavior should be >> accompanied by corresponding changes to the documentation, or be rejected. >> Code-changes that correspond with undocumented behavior are an opportunity >> to include some docs (not grounds to reject a code-review IMO, but >> certainly an opportunity to politely ask/suggest). >> >> Publishing more than one version (as generated from the respective >> branches/tags), is a solvable problem. >> >>>> On Thu, Mar 15, 2018 at 1:22 Kenneth Brotman >>>> <kenbrot...@yahoo.com.invalid >>>> wrote: >>>> >>>>> https://issues.apache.org/jira/browse/CASSANDRA-14313 >>>>> >>>>> >>>>> >>>>> For some reason I'm told by many committers that we should not >>>>> have sets of documentation for other versions than the current >>>>> version in a tree for that version. This has made it difficult, >>>>> maybe impossible to have documentation for all the supported >>>>> versions on the website at one time. >>>>> >>>>> >>>>> >>>>> As a solution I propose that we maintain the online documentation >>>>> in a separate repository that is managed as the current repository >>>>> under the guidance of the Apache Cassandra PMC (Project Management >>>>> Committee); and that in the new repository . . . >>>>> >>>>> >>>>> >>>>> Please see the jira. I hope it's a good answer to everyone. >> >> -- >> Eric Evans >> john.eric.ev...@gmail.com >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org >> For additional commands, e-mail: dev-h...@cassandra.apache.org >> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org >> For additional commands, e-mail: dev-h...@cassandra.apache.org >> >> -- > > Murukesh Mohanan, > Yahoo! Japan
