You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by "Jon Haddad (JIRA)" <ji...@apache.org> on 2018/03/14 16:38:00 UTC
[jira] [Commented] (CASSANDRA-14313) Maintain a separate repository
for the online documentation
[ https://issues.apache.org/jira/browse/CASSANDRA-14313?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16398848#comment-16398848 ]
Jon Haddad commented on CASSANDRA-14313:
----------------------------------------
{quote}
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.
{quote}
True, we ship the docs that correlate to the version that's released.
{quote}
This has made it difficult, maybe impossible to have documentation for all the supported versions on the website at one time.
{quote}
This isn't true at all. The docs for each version need to be built and put in a directory for each version on the site repo itself. That's a normal build process. The links for nav / etc need to be updated to support multiple versions. The site is here: https://svn.apache.org/repos/asf/cassandra/site
{quote}
Maintain the code in html, css and javascript so changes can be made easily using any number of programs.
That we immediately copy the current code to a new repository, convert it to html, css and javascript, convert it into a multi-version form and then switch over to it from now on for the online documentation.
{quote}
Absolutely not. Having the docs in sphinx means they are based on templates and can be easily rebuilt. This is a solved problem already for a million projects, regressing to manually editing HTML / CSS / JS would be a massive waste of time and doesn't help anyone.
I'm a firm -1 on this. I've built docs out for a number of projects over the years. This isn't the best set of docs, but certainly not the worst. If anything we could move to a better toolset (hugo for everything), but making everyone work with HTML / CSS / JS isn't going to get the docs any more attention than it does now.
> Maintain a separate repository for the online documentation
> -----------------------------------------------------------
>
> Key: CASSANDRA-14313
> URL: https://issues.apache.org/jira/browse/CASSANDRA-14313
> Project: Cassandra
> Issue Type: Improvement
> Reporter: Kenneth Brotman
> Priority: Major
>
> 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 we:
> # Maintain the code in html, css and javascript so changes can be made easily using any number of programs.
> # That we immediately copy the current code to a new repository, convert it to html, css and javascript, convert it into a multi-version form and then switch over to it from now on for the online documentation.
> I ask you to consider that right now there is not much on the web site. Many of us have the skill set to do this work in a matter of days. I can myself.
> Therefore, if this is agreeable to everyone, whether no one else helps or not, I will make sure its done over a two week period of time.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cassandra.apache.org
For additional commands, e-mail: commits-help@cassandra.apache.org