Well pickle my cucumbers Jon! It's good to know that you have experience with Hugo, see it as a good fit and that all has been well. I look forward to the jira epic!
How exactly does the group make such a decision: Call for final discussion? Call for vote? Wait for the PMC to vote? Kenneth Brotman -----Original Message----- From: Jon Haddad [mailto:jonathan.had...@gmail.com] On Behalf Of Jon Haddad Sent: Thursday, March 15, 2018 9:24 AM To: dev@cassandra.apache.org Subject: Re: A JIRA proposing a seperate repository for the online documentation 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?focusedCommentI > d=16211365&page=com.atlassian.jira.plugin.system.issuetabpanels:commen > t-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 --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org For additional commands, e-mail: dev-h...@cassandra.apache.org
