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

Jump to bottom

incremental docs build #16826

Closed
mppf opened this issue Dec 8, 2020 · 5 comments · Fixed by #16835
Closed

incremental docs build #16826

mppf opened this issue Dec 8, 2020 · 5 comments · Fixed by #16835
Labels
area: Docs area: Tools

Comments

@mppf
Copy link
Member

mppf commented Dec 8, 2020 •
edited

Running make docs currently takes some time. However it's possible for it to be updated to be incremental.

sphinx-build is supposed to already be incremental by default with the version we have.

We generate rst/{modules,builtins} using chpldoc, then we copy in an index file from rst/meta/{modules,builtins}. These copies prevent sphinx-build from being incremental (since the files have been modified).

We could change these to a copy-only-if-modified strategy. But, then we'd still run chpldoc. We could update the chpldoc build to only update modules that were modified first if the chpldoc command is taking up a significant amount of time in make docs.
@mppf
Copy link
Member Author

mppf commented Dec 8, 2020

Perhaps util/config/update-if-different could help here.

It looks to me like by far most of the make docs build is in the sphinx-build (vs chpldoc).

@lydia-duncan

This comment has been minimized.

Sign in to view
@mppf

This comment has been minimized.

Sign in to view
@bradcray
Copy link
Member

bradcray commented Dec 8, 2020

This sounds like a dream come true.

@mppf mppf mentioned this issue Dec 9, 2020
Merged
1 task
@mppf
Copy link
Member Author

mppf commented Dec 9, 2020

PR #16835 will do it but we need a change to sphinxcontrib-chapeldomain chapel-lang/sphinxcontrib-chapeldomain#45

mppf added a commit that referenced this issue Dec 14, 2020
@mppf
Merge pull request #16835 from mppf/make-docs-incremental
06cf289 
Adjust 'make docs' to do an incremental build

Resolves #16826

Note, #16862 /
chapel-lang/sphinxcontrib-chapeldomain#45 is
required for this change to function properly - but this branch has those
changes.

This PR adjusts `make docs` to do an incremental sphinx build. For now,
the `chpldoc` command always runs, but the scripts only update the source
files for `sphinx-build` if they are different.

This brings a `make docs` after a minor change to about 10 seconds.

Details:
 * Adjusts `util/config/update-if-different` to include a mode argument
   (`--update` or `--copy`) and adjusts the existing calls to it to use
   the `--update` argument.
 * Added `--copy` mode to `util/config/update-if-different` that will
   copy all updated source files (recursively) and delete things in the
   dst directory not present in src.
 * Does the module docs build steps by first constructing the rst sources
   in a subdirectory of build/doc/ and then using `update-if-different
   --copy` from here (so that removed files can be correctly handled)
 * Updated Makefiles for `make docs` to avoid deleting "build" directory
   (since we can use it again, incrementally)
 * Removes a lot of command echoing for this process. One can use `make
   SHELL='sh -x' docs` to see the commands again.

Reviewed by @ben-albrecht and @lydia-duncan - thanks!

- [x] full local testing
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
area: Docs area: Tools
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Adjust 'make docs' to do an incremental build mppf/chapel
3 participants
@lydia-duncan @mppf @bradcray