Fix documentation

.circleci/config.yml

@@ -18,23 +18,25 @@ jobs:
             echo "source /tmp/venv/openfisca_doc/bin/activate" >> $BASH_ENV
 
       - run:
-          name: Install app dependencies
-          command: |
-            pip install --upgrade pip
-            pip install -r requirements.txt --use-deprecated=legacy-resolver
+          name: Install doc dependencies
+          command: make install
 
       - save_cache:
           key: dependency-cache-{{ checksum "requirements.txt" }}
           paths:
             - /tmp/venv/openfisca_doc
 
       - run:
-          name: Build app
-          command: make html
+          name: Test doc
+          command: make test
+
+      - run:
+          name: Build doc
+          command: make build
 
       - run:
-          name: Run app
-          command: python -m http.server 8000 --directory build/html
+          name: Serve doc
+          command: make prod
           background: true
 
       - run:

Makefile

@@ -13,11 +13,29 @@ help:
 
 .PHONY: help Makefile
 
+# Install doc dependencies.
+install:
+	@pip install --upgrade pip
+	@pip install -r requirements.txt --use-deprecated=legacy-resolver
+
+# Build the doc.
+build:
+	@${MAKE} html
+
+# Test the doc.
+test:
+	@${MAKE} dummy SPHINXOPTS="-n -q -W"
+
+# Serve the documentation in dev mode.
+dev:
+	@rm -Rf $(BUILDDIR)
+	@sphinx-autobuild $(SOURCEDIR) $(BUILDDIR)
+
+# Serve the documentation in prod mode.
+prod:
+	@python -m http.server 8000 --directory build/html
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-dev:
-	rm -Rf $(BUILDDIR)
-	sphinx-autobuild $(SOURCEDIR) $(BUILDDIR)

README.md

@@ -7,15 +7,15 @@
 To install dependencies, run:
 
 ```
-pip install -r requirements.txt --use-deprecated=legacy-resolver
+make install
 ```
 
 ## Build
 
 To build the HTML documentation, run:
 
 ```
-make html
+make build
 ```
 
 The HTML output will be generated in the `build/html` directory.
@@ -30,6 +30,56 @@ make dev
 
 The documentation will be served on `http://127.0.0.1:8000`
 
+## Test
+
+To test the documentation, run:
+
+```
+make test
+```
+
+## Fixing the doc
+
+If the tests fail, here's what you can do:
+
+1. If the errors also concern OpenFisca-Core, please take a look at the [README](https://github.com/openfisca/openfisca-core/blob/master/README.md).
+
+2. If not, clone & install the documentation:
+
+```
+git clone https://github.com/openfisca/openfisca-doc
+make install
+```
+
+3. create a branch to correct the problems:
+
+```
+git checkout -b fix-doc
+```
+
+4. Fix the offending problems.
+
+You can test-drive your fixes by checking that each change works as expected:
+
+```
+make test
+```
+
+5. Commit at each step, so you don't accidentally lose your progress:
+
+```
+git add -A && git commit -m "Fixed missing doctree"
+```
+
+6. Once you're done, push your changes:
+
+```
+git push origin `git branch --show-current`
+```
+
+7. Finally, open a [pull request](https://github.com/openfisca/openfisca-doc/compare/master...fix-doc).
+
+That's it! 🙌
 
 ## Technical note on links
 

requirements.txt

@@ -1,8 +1,8 @@
 --editable git+https://github.com/openfisca/openfisca-core.git@master#egg=OpenFisca-Core[dev]
-docutils==0.12
+docutils==0.13.1
 guzzle_sphinx_theme==0.7.11
 recommonmark==0.4
 sphinx-autobuild==0.7.1
 sphinx-markdown-tables==0.0.9
-Sphinx==1.5
+Sphinx==1.5.1
 sphinx_argparse==0.2.5

source/conf.py

@@ -31,6 +31,11 @@
     'sphinxarg.ext',
 ]
 
+intersphinx_mapping = {
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    }
+
 source_parsers = {
     '.md': CommonMarkParser,
 }

source/openfisca-python-api/errors.rst

@@ -0,0 +1,8 @@
+======
+Errors
+======
+
+.. module:: openfisca_core.errors
+
+.. autoclass:: VariableNameConflictError
+    :members:

source/openfisca-python-api/holder.rst

@@ -2,5 +2,7 @@
 Holders
 =======
 
-.. automodule:: openfisca_core.holders
+.. module:: openfisca_core.holders
+
+.. autoclass:: Holder
     :members:

source/openfisca-python-api/index.md

@@ -20,6 +20,8 @@ Modules:
    enum_array
    holder
    simulation_generator
+   periods
+   errors
 ```
 
 Scripts:

source/openfisca-python-api/parameters.rst

@@ -2,5 +2,16 @@
 Parameters
 ==========
 
-.. automodule:: openfisca_core.parameters
+.. module:: openfisca_core.parameters
+
+.. autoclass:: ParameterNodeAtInstant
+    :members:
+
+.. autoclass:: ParameterNode
+    :members:
+
+.. autoclass:: Parameter
+    :members:
+
+.. autoclass:: ParameterScale
     :members:

source/openfisca-python-api/periods.rst

@@ -0,0 +1,8 @@
+=======
+Periods
+=======
+
+.. module:: openfisca_core.periods
+
+.. autoclass:: Instant
+    :members:

source/openfisca-python-api/simulations.rst

@@ -2,5 +2,7 @@
 Simulation
 ==========
 
-.. autoclass:: openfisca_core.simulations.Simulation
+.. module:: openfisca_core.simulations
+
+.. autoclass:: Simulation
     :members: calculate, get_array, get_holder, get_memory_usage

source/openfisca-python-api/tax-benefit-system.rst

@@ -2,5 +2,7 @@
 TaxBenefitSystem
 =================
 
-.. automodule:: openfisca_core.taxbenefitsystems
+.. module:: openfisca_core.taxbenefitsystems
+
+.. autoclass:: TaxBenefitSystem
     :members:

source/openfisca-python-api/variables.rst

@@ -2,5 +2,10 @@
 Variables
 =========
 
-.. automodule:: openfisca_core.variables
+.. module:: openfisca_core.variables
+
+.. autoclass:: Variable
+    :members:
+
+.. automodule:: openfisca_core.variables.typing
     :members: