On Thu, Mar 15, 2018 at 11:40 AM, Kenneth Brotman <kenbrot...@yahoo.com.invalid> wrote: > 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?
Good question! Decisions like this are made by consensus; As the person who is attempting to do something, you discuss your ideas with the group, listen to the feedback of others, and develop consensus around a direction. This is more difficult than demanding your way, or having someone(s) in a position of absolute power tell you what you can and cannot do, but the result is better. > -----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 > -- 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
