cassandra-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Evan Prothro (JIRA)" <j...@apache.org>
Subject [jira] [Comment Edited] (CASSANDRA-12804) CQL docs table of contents links are broken
Date Wed, 19 Oct 2016 21:47:58 GMT

    [ 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:47 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/eprothro/cassandra/tree/12804-3.X

This is my first patch attempt to Cassandra, apologies if I'm starting things off 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?

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 (pull request only opened for easy view of diff)

This is my first patch attempt to Cassandra, apologies if I'm starting things off wrong.


> 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: Minor
>
> 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)

Mime
View raw message