Faster makefile for doc development offline #6623
Conversation
Pierre-Sassoulas
added
Enhancement ✨
Pull Request Test Coverage Report for Build 2331129273
💛 - Coveralls |
Pierre-Sassoulas
force-pushed
the
faster-makefile-for-doc
branch
from
2f1d6e1 to
2ea610a
Compare
| @@ -13,7 +13,7 @@ PYTHONPATH = | |||
| # Internal variables. | |||
| PAPEROPT_a4 = -D latex_paper_size=a4 | |||
| PAPEROPT_letter = -D latex_paper_size=letter | |||
| ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees -T -E -W --keep-going $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | |||
| ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees -T -W --keep-going $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | |||
There was a problem hiding this comment.
-E don't use a saved environment, always read all files
In the CI we have a fresh environment, so this option is just making repeated build slower locally
doc/Makefile
Outdated
|
|
||
| html: build-html | ||
| @echo "Install dependencies" | ||
| $(PIP) install -r requirements.txt |
There was a problem hiding this comment.
I think the dependencies should be installed before calling build-html right?
There was a problem hiding this comment.
Fixed in latest commit.
doc/development_guide/contribute.rst
Outdated
| @@ -87,6 +87,10 @@ Tips for Getting Started with Pylint Development | |||
| Building the documentation | |||
| ---------------------------- | |||
|
|
|||
| We use **tox** for building the documentation:: | |||
| You can use the makefile and build-html command for building the documentation during developement:: | |||
There was a problem hiding this comment.
Let's suggest to run make html if you want to build the documentation and use build-html if you want to quickly test a small change. I think it's good to have make html be the standard as we could other checks next to linkcheck that would then be run automatically locally like a "documentation pre-commit".
doc/requirements.txt
Outdated
| @@ -1,4 +1,3 @@ | |||
| Sphinx==4.5.0 | |||
| sphinx-reredirects<1 | |||
| furo==2022.4.7 | |||
There was a problem hiding this comment.
We need the -e . for RTD as it needs access to pylint. We provide doc/requirements.tx while we're cd'ed into root.
I know I looked into this previously but couldn't figure out an elegant solution of allowing both RTD and cd docs + pip install -r ... to work.
There was a problem hiding this comment.
How about we suggest to install from the root with doc/requirements.txt, and we remove the requirement from the makefile ? (I.e. it's the job of the prepare-base job to install the proper dependencies.)
There was a problem hiding this comment.
Can we cd in a makefile? That way we could cd before and after installing the documentation dependencies.
I do think it would be nice to have one command you can run to completely make the documentation without any further trouble.
In the CI we have a fresh environnement, so this option is just making repeated build slower locally
Pierre-Sassoulas
force-pushed
the
faster-makefile-for-doc
branch
from
fe965d2 to
21f099a
Compare
Pierre-Sassoulas
force-pushed
the
faster-makefile-for-doc
branch
from
21f099a to
b94d9ac
Compare
Pierre-Sassoulas
force-pushed
the
faster-makefile-for-doc
branch
from
89bb089 to
95ed95f
Compare
Pierre-Sassoulas
added
the
Maintenance
Type of Changes
Description
I did a lot of doc modification recently for #6589 and the makefile installing dependency each time is taking a lot of time unnecessarily. I'm also thinking about lazy generating message files etc.