On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman <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 site: https://murukeshm.github.io/cassandra/ <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 ) 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
