docs: rework docs-project, allow doctest option #606
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
after #550 the docs project should not need the Oscar packages anymore
copy existing Project and develop all required packages in Oscar.doc_init to make sure everything is loaded from the same paths as in the currently loaded Oscar packages. also avoids some resolve-issues and issues arising from outdated manifest files in docs/ There is also a flag to specify a custom directory for the docs-project which is used by the CI, but will modify the docs/Project.toml file.
fingolfin
approved these changes
Aug 9, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
To make the
build_doc()process a little more robust I have removed everything except forDocumenter*fromdocs/Project.toml. (Also Kroki, i.e. this obsoletes #603)These entries caused various issues because without a corresponding Manifest.toml telling julia to use the Oscar-dev-dir the Pkg resolver failed in some cases. But keeping a manifest in that place can cause other issues, because people tend to forget to explicitly update that project.
The docs building process works like this in the background:
build_docis called a new environment with a copy of thisdocs/Project.tomlis created in/tmp/jl_somethingPkg.developwith the currently active path indoc_init(called automatically frombuild_doc)This also makes sure that the doctests and the docbuild are run with the correct versions of Oscar, Hecke, Nemo, AbstractAlgebra (e.g. if one uses a dev'd version of one of these).
All the resulting docs and temporary files are still in the
docssubdirectory. (Only Project.toml and Manifest.toml are in that temporary directory)I have also added
doctestandstrictflags tobuild_doc()which default tofalse. (fixes #604)Except for these flags there are no user-facing changes here.
For the CI I have added a keyword argument to
doc_initto use a custom path for the docs-project now used in.github/workflows/Docu.ymlto make sure that directory is still alive for the next github actions steps.