Make building the package docs more convenient #2173
Conversation
The `sources` entry in `docs/Project.toml` helps ensure the correct version of the package is used. There is also now a way to override the `doctest` test setting, so that one can turn them off for a quick test, or enable the `fix` mode for updating examples.
| Documenter = "1" | ||
|
|
||
| [sources] | ||
| AbstractAlgebra = {path = ".."} |
There was a problem hiding this comment.
I believe this is an unambiguous win and can be merged.
| # DOCTEST=off julia --proj=docs docs/make.jl | ||
| # | ||
| using Pkg | ||
| Pkg.update() |
There was a problem hiding this comment.
This one is debatable I guess, and perhaps indeed clearly bad (as it may e.g. hinder CI). The main reason I put it in is because I feel forgetting to run update in your docs environment is a common cause of issues.
Perhaps it should be changed to instantiate or entirely dropped. If we drop it, I think we should at least put in language into the comment above that recommends running the update manually in that environment on occasion.
Or, we could keep it, but add a way to control it via a command argument and/or environment var, just like the doctest. (And what the default value would be could be debated).
There was a problem hiding this comment.
In the past, I used to dev the main package into the docs environment. This then did not need any updating of the docs environment at all. (will look more in-depth at this PR later)
| if "--fix" in ARGS | ||
| doctest_arg = :fix | ||
| else | ||
| tmp = get(ENV, "DOCTEST", "true") |
There was a problem hiding this comment.
I think it is overkill to use both an env variable and and a command line argument to turn on "fix" mode. Thing is, I started with the idea of adding a command line argument, and just --fix, but then realized I also want to be able to turn off the doctests entirely. And then I got a bit lazy, as I'd have to decide what the args should be named (--doctest=on/off/fix?) and how to parse it ;-).
I think overall I'd find a command line argument nicer, and would be willing to implement it properly, but before I spend effort on it, I'd like to find out what others think.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #2173 +/- ##
=======================================
Coverage 87.93% 87.93%
=======================================
Files 127 127
Lines 31776 31776
=======================================
Hits 27941 27941
Misses 3835 3835 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
What about the |
|
I don't like the |
|
(In particular I have an extended version of this using Revise and for repeated rebuilds of the docs. I'll try to get it cleaned up and into another PR, but I think it might actually be better to do one for Hecke or Oscar first. We'll see. Might also be a good idea if @thofma @lgoettgens and me sat on a Zoom (?) call for a bit to talk about it. But we are all busy and this is hardly a priority right now... |
|
What is is "new" idea how to build the documentation? As in how and what command? |
|
Without Revise support I have a hard time imagening how doing |
The
sourcesentry indocs/Project.tomlhelps ensure the correct version of the package is used.There is also now a way to override the
doctesttest setting, so that one can turn them off for a quick test, or enable thefixmode for updating examples.This may need some discussion before it gets merged and rolled out to perhaps some more of our repos; I'll add some inline comments to relevant code sections