Details

    • Bug
    • Status: Open
    • Normal
    • Resolution: Unresolved
    • 3.11.x, 4.0.x
    • Legacy/CQL
    • None
    • Normal
    • Normal
    • Hide

      See PRs

      Show
      See PRs

    Description

      Cqlsh still points to the "old" textile CQL doc, but that's not really maintain anymore now that we have the new doc (which include everything the old doc had and more). We should update cqlsh to point to the new doc so we can remove the old one completely.

      Any takers?

      Attachments

        Issue Links

          Activity

            Sylvain, do we still need this? I'll take it on.

            It looks like the old docs were online at https://cassandra.apache.org/doc/cql3/CQL-3.2.html and available inside the user's Cassandra directory at the relative path /doc/cql3/CQL.html, and you want to point to the new docs at http://cassandra.apache.org/doc/latest/cql, right?

            How many versions back should this update go? Since this is classified as a Bug, I could go as far back as 3.0, but if you want me to prioritize a more recent version in support of releasing 4.0, I could start on a higher version.

             

             

            ptbannister Patrick Bannister added a comment - Sylvain, do we still need this? I'll take it on. It looks like the old docs were online at  https://cassandra.apache.org/doc/cql3/CQL-3.2.html and available inside the user's Cassandra directory at the relative path /doc/cql3/CQL.html, and you want to point to the new docs at http://cassandra.apache.org/doc/latest/cql , right? How many versions back should this update go? Since this is classified as a Bug, I could go as far back as 3.0, but if you want me to prioritize a more recent version in support of releasing 4.0, I could start on a higher version.    
            rustyrazorblade Jon Haddad added a comment -

            ptbannister, Yes, I think we still need this. It looks like a small enough patch, the same patch should work on 3.0 and up. I'll assign to you.

            rustyrazorblade Jon Haddad added a comment - ptbannister , Yes, I think we still need this. It looks like a small enough patch, the same patch should work on 3.0 and up. I'll assign to you.
            ptbannister Patrick Bannister added a comment - - edited

            Reading doc/README.md, I see we're building our docs at http://cassandra.apache.org/doc/latest/cql/index.html with the gen-doc target in build.xml.

            cassandra-3.0 doesn't have the source for the new docs or the gen-doc target. If we want to point cqlsh to the new docs in 3.0 then we also need to patch the new docs into 3.0.

            I'll start working on 3.11 and trunk. In the meantime, I'd appreciate some feedback for whether it would be reasonable to "backport" the new docs to 3.0.

            ptbannister Patrick Bannister added a comment - - edited Reading doc/README.md, I see we're building our docs at http://cassandra.apache.org/doc/latest/cql/index.html with the gen-doc target in build.xml. cassandra-3.0 doesn't have the source for the new docs or the gen-doc target. If we want to point cqlsh to the new docs in 3.0 then we also need to patch the new docs into 3.0. I'll start working on 3.11 and trunk. In the meantime, I'd appreciate some feedback for whether it would be reasonable to "backport" the new docs to 3.0.

            It looks like the docs aren't quite the same across versions. We're on different versions of the CQL spec:

            • 3.0 is up to CQL 3.4.0
            • 3.11.2 has CQL 3.4.4
            • trunk has CQL 3.4.5

            There are some major changes between these versions, so I don't think it's possible to simply backport the 3.11.2 docs to 3.0.

            ptbannister Patrick Bannister added a comment - It looks like the docs aren't quite the same across versions. We're on different versions of the CQL spec: 3.0 is up to CQL 3.4.0 3.11.2 has CQL 3.4.4 trunk has CQL 3.4.5 There are some major changes between these versions, so I don't think it's possible to simply backport the 3.11.2 docs to 3.0.

            Please see attached 13047-3.11.txt, or pull branch 13047-3.11-dev from my fork at https://github.com/ptbannister/cassandra, for a patch for 3.11. The same changes also work for trunk (although the CHANGES.txt message update in the 3.11 patch doesn't apply cleanly on CHANGES.txt in the trunk).

            ptbannister Patrick Bannister added a comment - Please see attached 13047-3.11.txt, or pull branch 13047-3.11-dev from my fork at https://github.com/ptbannister/cassandra , for a patch for 3.11. The same changes also work for trunk (although the CHANGES.txt message update in the 3.11 patch doesn't apply cleanly on CHANGES.txt in the trunk).

            We should probably wait until CASSANDRA-13907 and point to the correct document version, instead of always showing the most recent CQL spec.

            spod Stefan Podkowinski added a comment - We should probably wait until CASSANDRA-13907 and point to the correct document version, instead of always showing the most recent CQL spec.

            I would be happy to revise my work after 13907, I think it would provide much better documentation!

            ptbannister Patrick Bannister added a comment - I would be happy to revise my work after 13907, I think it would provide much better documentation!

            Concur with recommendation by spodxx@gmail.com that cqlsh should link to versioned documentation for the corresponding CQL spec.

            ptbannister Patrick Bannister added a comment - Concur with recommendation by spodxx@gmail.com that cqlsh should link to versioned documentation for the corresponding CQL spec.
            nmschorr Nancy Schorr added a comment - - edited

            Is this bug related to the problem of typing "help date" or help <any command> which sends the user to a non-existent webpage?  For instance, in cqlsh type "help time" and the browser is opened and attempts to go to "https://cassandra.apache.org/doc/cql3/CQL-3.2.html#usingtime" which doesn't exist.  The page says:  "Not Found  The requested URL /doc/cql3/CQL-3.2.html was not found on this server."  I'm using 3.11.2 on Centos.  Seems like the root cause is the same as this bug, so I don't want to clutter the system in case it is as I'm new to this project.  

             

            nmschorr Nancy Schorr added a comment - - edited Is this bug related to the problem of typing "help date" or help <any command> which sends the user to a non-existent webpage?  For instance, in cqlsh type "help time" and the browser is opened and attempts to go to "https://cassandra.apache.org/doc/cql3/CQL-3.2.html#usingtime" which doesn't exist.  The page says:  "Not Found  The requested URL /doc/cql3/CQL-3.2.html was not found on this server."  I'm using 3.11.2 on Centos.  Seems like the root cause is the same as this bug, so I don't want to clutter the system in case it is as I'm new to this project.    

            nmschorr, yes, it sounds like you're experiencing the bug addressed by this ticket.

            ptbannister Patrick Bannister added a comment - nmschorr , yes, it sounds like you're experiencing the bug addressed by this ticket.
            nmschorr Nancy Schorr added a comment -

            Thanks Patrick. How about a redirect for "https://cassandra.apache.org/doc/cql3/CQL-3.2.html" to some kind of explanation or advice. At this point - all help in cqlsh is unavailable to the user.

            nmschorr Nancy Schorr added a comment - Thanks Patrick. How about a redirect for "https://cassandra.apache.org/doc/cql3/CQL-3.2.html" to some kind of explanation or advice. At this point - all help in cqlsh is unavailable to the user.

            Let's get an status update on CASSANDRA-13907.

            ptbannister Patrick Bannister added a comment - Let's get an status update on CASSANDRA-13907 .

            Looking at this in light of CASSANDRA-13047. Currently we have two versions of the docs: 3.11 for 3.11 and older, latest for 4.0. I anticipate the versions will be a moving target going forward. I'm thinking the answer to this is to have the versioned docs website redirect requests for all version numbers to the appropriate versioned docs for that version number.

            ptbannister Patrick Bannister added a comment - Looking at this in light of CASSANDRA-13047 . Currently we have two versions of the docs: 3.11 for 3.11 and older, latest for 4.0. I anticipate the versions will be a moving target going forward. I'm thinking the answer to this is to have the versioned docs website redirect requests for all version numbers to the appropriate versioned docs for that version number.
            jmckenzie Josh McKenzie added a comment -

            Ping on this. Anyone need a hand?

            jmckenzie Josh McKenzie added a comment - Ping on this. Anyone need a hand?

            It looks like the versioned docs website has progressed enough that this ticket could be completed. However, I should hand it off to somebody with more free time to work on it.

            ptbannister Patrick Bannister added a comment - It looks like the versioned docs website has progressed enough that this ticket could be completed. However, I should hand it off to somebody with more free time to work on it.

            I have a PR up I would appreciate some cursory look to validate the approach I took before moving further.

            First I fixed all the broken links I found around. But instead of switching to the new online docs always, I left things working both for local and online docs and their diff format/anchors. I thought this would be valuable bc in several occasions I've known of people working in envs with restricted/no online access (datacenters, etc), hence being cut off any docs when you need it most. Having the docs available locally is a huge added value imo.

            I suggest closing this ticket with the attached approach. Then in a later one fix things so releases come with bundled docs and fix the py code accordingly. Wdyt?

            bereng Berenguer Blasi added a comment - I have a PR up I would appreciate some cursory look to validate the approach I took before moving further. First I fixed all the broken links I found around. But instead of switching to the new online docs always, I left things working both for local and online docs and their diff format/anchors. I thought this would be valuable bc in several occasions I've known of people working in envs with restricted/no online access (datacenters, etc), hence being cut off any docs when you need it most. Having the docs available locally is a huge added value imo. I suggest closing this ticket with the attached approach. Then in a later one fix things so releases come with bundled docs and fix the py code accordingly. Wdyt?

            Hey bereng, I can review but I suspect this might be outdated after all latest changes to docs, website...

            Should we rebase? 

            e.dimitrova Ekaterina Dimitrova added a comment - Hey bereng , I can review but I suspect this might be outdated after all latest changes to docs, website... Should we rebase? 
            bereng Berenguer Blasi added a comment - - edited

            Hi e.dimitrova thx for looking.

            Before moving forward with rebases etc there's an underlying q to resolve. We have a skinny CQL doc page in tree with the releases. We can't completely move online bc we can have people using commands on envs with no connectivity to check docs online, such as secure DCs. 4.0+ I think we should replace that with the full docs in-tree. Wdyt?

            We should maybe raise this in the ML...

            bereng Berenguer Blasi added a comment - - edited Hi e.dimitrova thx for looking. Before moving forward with rebases etc there's an underlying q to resolve. We have a skinny CQL doc page in tree with the releases. We can't completely move online bc we can have people using commands on envs with no connectivity to check docs online, such as secure DCs. 4.0+ I think we should replace that with the full docs in-tree. Wdyt? We should maybe raise this in the ML...

            I think first we should figure out why In-tree we have only skinny page, I suspect there might be a good reason for that, maybe...

            e.dimitrova Ekaterina Dimitrova added a comment - I think first we should figure out why In-tree we have only skinny page, I suspect there might be a good reason for that, maybe...

            Fired an ML thread before making such a big change

            bereng Berenguer Blasi added a comment - Fired an ML thread before making such a big change

            ML thread here. Seems there might be apetite to bundle docs locally so I will try to coordinate in those tickets

            bereng Berenguer Blasi added a comment - ML thread here . Seems there might be apetite to bundle docs locally so I will try to coordinate in those tickets

            Returning to work in progress based on your comment and the ML thread pointed. 

            e.dimitrova Ekaterina Dimitrova added a comment - Returning to work in progress based on your comment and the ML thread pointed. 

            Iiuc we're still moving docs around so we better wait for things to settle down?

            bereng Berenguer Blasi added a comment - Iiuc we're still moving docs around so we better wait for things to settle down?

            Docs seem to have just moved into the state we needed them. I will jump again into this one

            bereng Berenguer Blasi added a comment - Docs seem to have just moved into the state we needed them. I will jump again into this one

            We just found this while working on CASSANDRA-18185. It would be nice to move this forward. I think 18185 can be merged independently from this.

            cc neshkeev

            smiklosovic Stefan Miklosovic added a comment - We just found this while working on CASSANDRA-18185 . It would be nice to move this forward. I think 18185 can be merged independently from this. cc neshkeev

            I don't quite follow. c18185 seems to be about typos? Whereas this one is on hold until docs settle down which polandll is looking into atm iiuc

            bereng Berenguer Blasi added a comment - I don't quite follow. c18185 seems to be about typos? Whereas this one is on hold until docs settle down which polandll is looking into atm iiuc

            Cqlsh still points to the "old" textile CQL doc, but that's not really maintain anymore

            The textile doc was updated in CASSANDRA-17709 so I don't think this ticket is necessary any longer.

            brandon.williams Brandon Williams added a comment - Cqlsh still points to the "old" textile CQL doc, but that's not really maintain anymore The textile doc was updated in CASSANDRA-17709 so I don't think this ticket is necessary any longer.

            There were bugfixes in here as well, such as falling back to the online docs but on the correct version, not 'latest' always. So I think there's still some good here but no point in doing anything until the in-tree docs happens.

            bereng Berenguer Blasi added a comment - There were bugfixes in here as well, such as falling back to the online docs but on the correct version, not 'latest' always. So I think there's still some good here but no point in doing anything until the in-tree docs happens.

            People

              bereng Berenguer Blasi
              slebresne Sylvain Lebresne
              Berenguer Blasi
              Votes:
              1 Vote for this issue
              Watchers:
              9 Start watching this issue

              Dates

                Created:
                Updated:

                Time Tracking

                  Estimated:
                  Original Estimate - Not Specified
                  Not Specified
                  Remaining:
                  Remaining Estimate - 0h
                  0h
                  Logged:
                  Time Spent - 0.5h
                  0.5h