Skip to content
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

Add make option to build local changes #92

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add make option to build local changes #92

Show file tree
Hide file tree
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
4 changes: 4 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@ html: Makefile
@$(SPHINXBUILDMULTIVERSION) "$(SOURCEDIR)" "$(BUILDDIRHTML)" $(SPHINXOPTS) $(O)
cp source/_templates/redirect.html "$(BUILDDIRHTML)/index.html"

# make local: Only builds local files, including all files that aren't committed
local: Makefile
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
Expand Down
26 changes: 24 additions & 2 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ For more detailed usage instructions, see the `Open Ephys Doc Template <https://
How to build this documentation
===============================

Previewing local changes
------------------------
Building local changes with multi-versioning
--------------------------------------------

Due to how sphinx-multiversion is configured (see below), in order to view the local changes that
are made, it is necessary to create a file at the top-most level of the repo named "whitelist.txt".
Expand All @@ -36,6 +36,28 @@ like the following example:
issue-85
issue-86

Then, follow the instructions below on how to set up the environment correctly, commit your changes
to the current branch, and call `pipenv run make html`. This will automatically include all branch
names found in the whitelist file in the multiversion build. If there are branches that need to be
removed, since they are no longer being worked on, call `pipenv run make clean` to remove all files,
and then run `make html` again to create a fresh build.

Building local changes without committing
----------------------------------------

Since it can be a burden, and not a very useful workflow, to have to commit local changes to the
branch before building them, this section provides a method to build local changes from the edited
files before they are committed to the branch. One caveat, is that this method will break the
multiversion dropdown and the associated functionality, so only the local changes will be rendered
in the HTML pages.

Before building locally, it is recommended to run `pipenv run make clean` to remove the folder
hierarchy that might be created from the multi-versioning. This will prevent any conflicts with
naming.

Next, run `pipenv run make local` to build Sphinx only using the local files. In this format, there
will be one folder (docs/html) where all of the locally built HTML files will be located.

With pipenv (recommended)
-----------

Expand Down