CASSJAVA-109: Manual and API References after donation

[SiyaoIsHiding]

Removed previous obsolete files. Added the HTMLs automatically generated by mkdocs from the build script in this branch on the 4.19.0 tag.
Those HTMLs can be previewed here: https://siyaoishiding.github.io/java-driver/
As there is essentially nothing to review in the code in this PR, I hope we can merge this PR soon, so the doc will be up!
cc @absurdfarce and @lukasz-antoniak for review

[michaelsembwever]

Looking good ! Then we'll be able to point docs to

I think we need to change this file though (so we're not redirected away): https://github.com/apache/cassandra-java-driver/blob/gh-pages/index.html

All the other versions (and every subdirectory) has these redirecting index.html pages. Would it be possible, feasible, to regenerate docs for all versions (except those we are intentionally removing) ?

[SiyaoIsHiding]

this file index.html

This PR removes all the existing files, including the index.html. So after we merge this PR, there won't be any redirecting page.

All the other versions

Last time we talked about this on Slack, we decided to get the 4.19.0 page up first and then take care of the other versions later.
But, by "all the other versions," do you include the versions before donation?

[absurdfarce]

Agree with @SiyaoIsHiding ... my recollection was that we were going to get Javadoc for the most recent version up first and then sort out the multiple version question when 4.19.1 came out. Literally any available Javadoc will be an improvement over our current situation.

[absurdfarce]

So this is probably a minor nit but it seems... weird. When I go here and select any of the specified languages/frameworks I'm taken to a page that seems to follow the same format (same colors/layout etc.) but the nav bar on the left is just gone. I can get back out of it by clicking the browser's back button but this... seems weird. Why isn't this just another level in the hierarchy? It seems like that's what's happening in the Github rendering.

Is there some kind of configured limit on how deep the left nav is willing to go?

[absurdfarce]

Huh... clicking on the "Home" button on the top nav seems to do the same thing. Witness this page as an example.

Are we missing a config somewhere?

[michaelsembwever]

Last time we talked about this on Slack, we decided to get the 4.19.0 page up first and then take care of the other versions later.

Yes, totally agree– this isn't a blocker. Was just raising the question: if this is actually easy to generate for each version, and is just about top level directories for each version, there's no harm including it, if you feel it's easy and have time for it. (An aspect from the previous conversation IIRC was how to handle multiple versions, but here it seems it's sorted– just directories at the top-level, and the top-level readme just lists them manually…)

[SiyaoIsHiding]

Fixed the issue of navigation bar disappearing that Bret mentioned by adding nested pages to the nav path.
Added 4.18.0 and 4.18.1 there.

[aimurphy]

Not sure if you intended to address this in a subsequent PR or if it wasn't relevant, but there is some broken syntax, for example:

In any case, @SiyaoIsHiding, please let me know when this PR is merged, and I will update the incoming links here. I will also ask Ronnie to update our redirect banner from the earlier versions, if you don't end up republishing them.

[SiyaoIsHiding]

@aimurphy
Bret and I decided to try to merge this PR to get doc up first, and then another PR against 4.x branch to fix the broken texts/links in the manual, and the fix will go into the later doc, e.g. 4.19.1 manual.

[absurdfarce]

To follow up on @SiyaoIsHiding 's point above: there are three distinct phases of getting this documentation + build process in place:

• Initial push of HTML (from Markdown) + Javadoc so that we have something of our own in place
• A PR for 4.x updating links to the manual and API to the new location(s)
• A PR for 4.x containing anything we actually need to implement the build process (and possibly some docs for it as well)

My working assumption is that the paragraph(s) you cite above @aimurphy will go away in their entirety in the second step outlined above.

Note that we're only updating links to the manual + Javadoc for 4.x... we're not planning on retroactively fixing older releases. It seems entirely reasonable to expect that since release of documentation is a new addition to the project it will be supported (and continue to be supported) from that point going forward.

[aimurphy]

Note that we're only updating links to the manual + Javadoc for 4.x... we're not planning on retroactively fixing older releases. It seems entirely reasonable to expect that since release of documentation is a new addition to the project it will be supported (and continue to be supported) from that point going forward.

Yes this makes sense. I meant that I will update the links from the DataStax site to your new 4.18+ docs when you have published them. Currently, I am linking to the raw files in this repo - so I will replace those with your new links.

[absurdfarce]

Hmmmm, I'm wondering if we want to do that at all @aimurphy. The ASF is not taking any responsibility for pre-ASF releases (i.e. those done under the DataStax umbrella) and there's a reasonable argument for us doing the same.

Maybe once we have Javadoc + good docs up just update our site to say some variant of the docs you cited above... "this driver has now been donated to the ASF, you can find additional information about current releases here" and then link to the ASF site?

I'm just not sure we want to be in the business of hosting docs for, say, the 4.19.1 release (when it comes out).

[aimurphy]

I don't want to derail this PR - I will message you on Slack to explain.

[SiyaoIsHiding]

4.18.1 doc was missing in the previous commit, I added it there just now.
Both @michaelsembwever 's concern (multi-version) and @absurdfarce 's concern (nav disappeared) are gone. Please review again, thank you :D

[absurdfarce]

So the docs as written right now use absolute URLs for a lot of the Javadoc references, in part to enable a sort of split publishing: Javadocs can live in one place (in DataStax documentation historically) while the Markdown can get processed and published somewhere else. As just one example of what I'm talking about consider this section of core/README.md with links defined here.

We had discussed a three-fold conversion of docs in total:

• Generate new content to publish in GH branch (this PR)
• Create PR for process to do generation + publish
• Update links in the current documentation to point to the proper place

What I'm discussing here could be put off until we work on the third PR above. That's not a huge deal; we'd temporarily be pointing ASF users to the Javadoc for 4.17.0 hosted on the DataStax site but that would be addressed when the third PR is merged and we re-deploy.

I guess my question is... do we want to continue with this process of using absolute URLs to refer to Javadoc? We probably can switch over to something relative now, right? There are pluses and minuses to consider there... but it seemed worthwhile to ask the question.

[absurdfarce]

In conversation with some other groups internal to DataStax/IBM it came up that this process includes only the manual section of the docs. We don't have any rendering of the top-level README.md or the contribution guidelines in CONTRIBUTING.md with this process as implemented now (unless I missed something). It would be nice to get this content included, especially since we have another PR in-flight to update CONTRIBUTING.md to better reflect current practices.

[SiyaoIsHiding]

top-level README.md is included, at the navigation bar, click "HOME", and you will get here: https://siyaoishiding.github.io/java-driver/4.19.0/HOME-README/
CONTRIBUTING.md isn't tho. I can work on it.

[absurdfarce]

Reviewed this one more time with @SiyaoIsHiding in our regular meeting this morning. This PR as it stands represents a significant improvement over the current state of affairs (i.e. no documentation beyond Github rendering the Markdown) so we're going to merge it as it stands. As mentioned above we always knew we would need a follow-up PR to clean up some things, most notably all the Javadoc references in the Markdown. We'll take care of including README.md and CONTRIBUTING.md at that point.

[SiyaoIsHiding]

Squashed!