feat_enable_version_specific_docs #2170
Conversation
coderfender
force-pushed
the
feat_enable_version_specific_docs
branch
from
76e7376 to
9acf399
Compare
|
Doc update PR to resolve #510 . Changes should help us improve documentation and we can browse the docs between version |
|
Please review above change whenever you get a chance @andygrove , @kazuyukitanimura |
| %: Makefile | ||
| @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
| # Build docs and copy into versioned dir (like Spark does) | ||
| publish: html |
There was a problem hiding this comment.
How will this new target get invoked? .github/workflows/docs.yaml currently calls docs/build.sh which invokes make SOURCEDIR=pwd/temp html.
There was a problem hiding this comment.
Thank you for the review. I will update build.sh to reflect version specific doc generation and upload
| # Build docs and copy into versioned dir (like Spark does) | ||
| publish: html | ||
| @mkdir -p site/docs/$(PROJECT_VERSION) | ||
| @cp -r $(BUILDDIR)/html/* site/docs/$(PROJECT_VERSION)/ |
There was a problem hiding this comment.
The GitHub workflow will need to be updated to publish from the new location
There was a problem hiding this comment.
Thank you . I will go ahead and update the git workflow YAML file
| @cp -r $(BUILDDIR)/html/* site/docs/$(PROJECT_VERSION)/ | ||
| @rm -rf site/docs/latest | ||
| @ln -s $(PROJECT_VERSION) site/docs/latest | ||
| @echo "Docs published under site/docs/$(PROJECT_VERSION) and site/docs/latest" |
There was a problem hiding this comment.
This PR will result in all current content being deleted, so users visiting https://datafusion.apache.org/comet/ will get a 404 error. We'll need to think about the best way to handle that. Perhaps we need to set up redirects for current content to redirect to /latest?
There was a problem hiding this comment.
We will also need a way for users to see which versions we have documentation published for. Spark has https://spark.apache.org/documentation.html which is linked to from the top-level documentation menu.
There was a problem hiding this comment.
This is a great idea. Should we have a manifest page to route users to the right version specific documentation ? Also, It is my understanding that we will start supporting version specific documentation starting 0.9.0 ?
There was a problem hiding this comment.
I wonder if we should have two separate folders for the source content. We could have one folder for top-level content that is not specific to a particular version (main landing page and menu etc) and then a folder with all the version-specific content. What do you think?
There was a problem hiding this comment.
I don't mind which version we start doing this with. Perhaps it is easiest to start with the 0.10.0 release (we are tentatively planning a release in ~2 weeks time)
Which issue does this PR close?
Enable version specific documentation - comet
Closes #.
Rationale for this change
Current docs are directly fetched out of main branch irrespective of the release cycle. This limits the ability for the users to understand differences among versions
What changes are included in this PR?
Docs changes to publish version specific docs (URL)
How are these changes tested?
Local testing