Skip to content

feat_enable_version_specific_docs #2170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

feat_enable_version_specific_docs #2170

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 13 additions & 8 deletions docs/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,20 +19,25 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build

# Put it first so that "make" without argument is like "make help".
# Extract version from Cargo.toml (default)
PROJECT_VERSION := $(shell grep '^version' ../native/Cargo.toml | head -1 | cut -d '"' -f2)

help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile
html:
@echo "Building docs for version $(PROJECT_VERSION)"
@PROJECT_VERSION=$(PROJECT_VERSION) $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html"

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# Build docs and copy into versioned dir (like Spark does)
publish: html
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How will this new target get invoked? .github/workflows/docs.yaml currently calls docs/build.sh which invokes make SOURCEDIR=pwd/temp html.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the review. I will update build.sh to reflect version specific doc generation and upload

@mkdir -p site/docs/$(PROJECT_VERSION)
@cp -r $(BUILDDIR)/html/* site/docs/$(PROJECT_VERSION)/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The GitHub workflow will need to be updated to publish from the new location

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you . I will go ahead and update the git workflow YAML file

@rm -rf site/docs/latest
@ln -s $(PROJECT_VERSION) site/docs/latest
@echo "Docs published under site/docs/$(PROJECT_VERSION) and site/docs/latest"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)