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. 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? 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
