[ https://issues.apache.org/jira/browse/CASSANDRA-12804?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15589823#comment-15589823 ]
Evan Prothro edited comment on CASSANDRA-12804 at 10/19/16 9:00 PM: -------------------------------------------------------------------- I've looked at it further and it appears the CQL spec content in the new sphinx docs is a good replacement for the legacy html doc (IMHO). The notable difference is that the old docs didn't include Queries as part of DML statements, the new docs lump Queries into DML statements. I personally prefer the former, but the difference is probably only semantic. It would also appear that removing the legacy docs has a side effect of the build no longer including the cql docs. Is that a problem? Finally, it appears that the website is manually updated on occasion (e.g. not automatically on a release). They are currently out of date at 3.7, and the CSS results in noticeable width and navigation issues that hurt usability. The latter problems are solved in the latest version of the sphinx theme (https://cl.ly/hpXw). What about the following? 1. Change directory structure for legacy cql.html files on web from - /doc/cql3/ - CQL-2.1.html - CQL-2.2.html - CQL-3.0.html - CQL.css to - /doc/cql_2_1/ - CQL.html - CQL.css - /doc/cql_2_2/ - CQL.html - CQL.css - /doc/cql_3_0/ - CQL.html - CQL.css 2. Generate newest sphinx docs from 3.9 branch and push to website * This updates to latest release doc content * This fixes the existing formatting issues 3. Remove cql.textile, et al in 3.X branch A stab at that removal: https://github.com/apache/cassandra/pull/77 This is my first PR to Cassandra, apologies if I'm doing it wrong. was (Author: eprothro): I've looked at it further and it appears the CQL spec content in the new sphinx docs is a good replacement for the legacy html doc (IMHO). The notable difference is that the old docs didn't include Queries as part of DML statements, the new docs lump Queries into DML statements. I personally prefer the former, but the difference is probably only semantic. It would also appear that removing the legacy docs has a side effect of the build no longer including the cql docs. Is that a problem? A stab at that removal: https://github.com/apache/cassandra/pull/77 This is my first PR to Cassandra, apologies if I'm doing it wrong. It appears that the website is manually updated on occasion. They are currently out of date at 3.7, and the CSS has noticeable width issues. What about the following? 1. Change directory structure for legacy cql.html files on web from - /doc/cql3/ - CQL-2.1.html - CQL-2.2.html - CQL-3.0.html - CQL.css to - /doc/cql_2_1/ - CQL.html - CQL.css - /doc/cql_2_2/ - CQL.html - CQL.css - /doc/cql_3_0/ - CQL.html - CQL.css 2. Generate newest sphinx docs from 3.9 branch and push to website * This updates to latest release doc content * This fixes the existing formatting issues 3. Remove cql.textile, et al in 3.X branch > CQL docs table of contents links are broken > ------------------------------------------- > > Key: CASSANDRA-12804 > URL: https://issues.apache.org/jira/browse/CASSANDRA-12804 > Project: Cassandra > Issue Type: Bug > Components: Documentation and Website > Reporter: Evan Prothro > Priority: Trivial > > Example: Clicking on a link in the table of contents at > https://cassandra.apache.org/doc/cql3/CQL-3.0.html results in a 404 to > https://cassandra.apache.org/doc/cql3/CQL.html#Preamble > Links in the body work. > Table of contents link to the base file name (cql.html), but the html file is > cql-[version].html) -- This message was sent by Atlassian JIRA (v6.3.4#6332)