openfisca · bonjourmauko · Sep 9, 2021 · Aug 30, 2021 · Aug 28, 2021 · Aug 28, 2021
diff --git a/.circleci/config.yml b/.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
+          name: Test doc
+          command: make test
+
+      - run:
+          name: Build doc
           command: make html
 
       - run:
-          name: Run app
-          command: python -m http.server 8000 --directory build/html
+          name: Serve doc
+          command: make prod
           background: true
 
       - run:

diff --git a/Makefile b/Makefile
@@ -13,11 +13,25 @@ help:
 
 .PHONY: help Makefile
 
+# Install doc dependencies.
+install:
+	@pip install --upgrade pip
+	@pip install -r requirements.txt --use-deprecated=legacy-resolver
+
+# 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)
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 To install dependencies, run:
 
 ```
-pip install -r requirements.txt --use-deprecated=legacy-resolver
+make install
 ```
 
 ## Build
@@ -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
 

diff --git a/requirements.txt b/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
diff --git a/source/conf.py b/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,
 }

diff --git a/source/openfisca-python-api/entities.rst b/source/openfisca-python-api/entities.rst
@@ -2,8 +2,16 @@
 Entities
 ========
 
-.. autoclass:: openfisca_core.entities.Entity
+.. module:: openfisca_core.entities
+
+.. autoclass:: Role
+    :members:
+
+.. autoclass:: Entity
+    :members:
+
+.. autoclass:: GroupEntity
     :members:
 
-.. autoclass:: openfisca_core.entities.GroupEntity
+.. automodule:: openfisca_core.entities.helpers
     :members:
diff --git a/source/openfisca-python-api/enum_array.rst b/source/openfisca-python-api/enum_array.rst
@@ -2,10 +2,13 @@
 Enum & EnumArray
 ================
 
-.. currentmodule:: openfisca_core.indexed_enums
+.. module:: openfisca_core.indexed_enums
 
 .. autoclass:: Enum
   :members:
 
 .. autoclass:: EnumArray
   :members:
+
+.. automodule:: openfisca_core.indexed_enums.config
+    :members:
diff --git a/source/openfisca-python-api/errors.rst b/source/openfisca-python-api/errors.rst
@@ -0,0 +1,36 @@
+======
+Errors
+======
+
+.. module:: openfisca_core.errors
+
+.. autoclass:: CycleError
+    :members:
+
+.. autoclass:: EmptyArgumentError
+    :members:
+
+.. autoclass:: NaNCreationError
+    :members:
+
+.. autoclass:: ParameterNotFoundError
+    :members:
+
+.. autoclass:: ParameterParsingError
+    :members:
+
+.. autoclass:: PeriodMismatchError
+    :members:
+
+.. autoclass:: SituationParsingError
+    :members:
+
+.. autoclass:: SpiralError
+    :members:
+
+.. autoclass:: VariableNameConflictError
+    :members:
+
+.. autoclass:: VariableNotFoundError
+    :members:
+
diff --git a/source/openfisca-python-api/holder.rst b/source/openfisca-python-api/holder.rst
@@ -2,5 +2,10 @@
 Holders
 =======
 
-.. automodule:: openfisca_core.holders
+.. module:: openfisca_core.holders
+
+.. autoclass:: Holder
+    :members:
+
+.. automodule:: openfisca_core.holders.helpers
     :members:
diff --git a/source/openfisca-python-api/index.md b/source/openfisca-python-api/index.md
@@ -12,14 +12,15 @@ Modules:
    parameters
    reforms
    simulations
-   simulation_builder
    entities
    populations
    test_runner
    tracer
    enum_array
    holder
    simulation_generator
+   periods
+   errors
 ```
 
 Scripts:

diff --git a/source/openfisca-python-api/parameters.rst b/source/openfisca-python-api/parameters.rst
@@ -2,5 +2,35 @@
 Parameters
 ==========
 
-.. automodule:: openfisca_core.parameters
+.. module:: openfisca_core.parameters
+
+.. autoclass:: AtInstantLike
+    :members:
+
+.. autoclass:: Parameter
+    :members:
+
+.. autoclass:: ParameterAtInstant
+    :members:
+
+.. autoclass:: ParameterNode
+    :members:
+
+.. autoclass:: ParameterNodeAtInstant
+    :members:
+
+.. autoclass:: ParameterScale
+    :members:
+
+.. autoclass:: ParameterScaleBracket
+    :members:
+
+.. autoclass:: VectorialParameterNodeAtInstant
+    :members:
+
+
+.. automodule:: openfisca_core.parameters.helpers
+    :members:
+
+.. automodule:: openfisca_core.parameters.config
     :members:
diff --git a/source/openfisca-python-api/periods.rst b/source/openfisca-python-api/periods.rst
@@ -0,0 +1,17 @@
+=======
+Periods
+=======
+
+.. module:: openfisca_core.periods
+
+.. autoclass:: Period
+    :members:
+
+.. autoclass:: Instant
+    :members:
+
+.. automodule:: openfisca_core.periods.helpers
+    :members:
+
+.. automodule:: openfisca_core.periods.config
+    :members:
diff --git a/source/openfisca-python-api/populations.rst b/source/openfisca-python-api/populations.rst
@@ -2,8 +2,13 @@
 Populations
 ===========
 
+.. module:: openfisca_core.populations
+
 .. autoclass:: openfisca_core.populations.Population
-  :members: __call__, has_role, get_rank
+    :members: __call__, has_role, get_rank
 
 .. autoclass:: openfisca_core.populations.GroupPopulation
-  :members: all, any, max, min, nb_persons, sum
+    :members: all, any, max, min, nb_persons, sum
+
+.. automodule:: openfisca_core.populations.config
+    :members:
diff --git a/source/openfisca-python-api/reforms.rst b/source/openfisca-python-api/reforms.rst
@@ -2,5 +2,7 @@
 Reforms
 =======
 
-.. automodule:: openfisca_core.reforms
+.. module:: openfisca_core.reforms
+
+.. autoclass:: Reform
     :members:
diff --git a/source/openfisca-python-api/simulation_builder.rst b/source/openfisca-python-api/simulation_builder.rst
diff --git a/source/openfisca-python-api/simulations.rst b/source/openfisca-python-api/simulations.rst
@@ -1,6 +1,14 @@
-==========
-Simulation
-==========
+===========
+Simulations
+===========
 
-.. autoclass:: openfisca_core.simulations.Simulation
+.. module:: openfisca_core.simulations
+
+.. autoclass:: Simulation
     :members: calculate, get_array, get_holder, get_memory_usage
+
+.. autoclass:: SimulationBuilder
+    :members: build_from_dict, build_from_entities, build_from_variables, build_default_simulation, explicit_singular_entities
+
+.. automodule:: openfisca_core.simulations.helpers
+    :members:
diff --git a/source/openfisca-python-api/tax-benefit-system.rst b/source/openfisca-python-api/tax-benefit-system.rst
@@ -2,5 +2,7 @@
 TaxBenefitSystem
 =================
 
-.. automodule:: openfisca_core.taxbenefitsystems
+.. module:: openfisca_core.taxbenefitsystems
+
+.. autoclass:: TaxBenefitSystem
     :members:
diff --git a/source/openfisca-python-api/tracer.rst b/source/openfisca-python-api/tracer.rst
@@ -2,5 +2,25 @@
 Tracer
 ======
 
-.. automodule:: openfisca_core.tracers
+.. module:: openfisca_core.tracers
+
+.. autoclass:: ComputationLog
+    :members:
+
+.. autoclass:: FlatTrace
+    :members:
+
+.. autoclass:: FullTracer
+    :members:
+
+.. autoclass:: PerformanceLog
+    :members:
+
+.. autoclass:: SimpleTracer
+    :members:
+
+.. autoclass:: TraceNode
+    :members:
+
+.. autoclass:: TracingParameterNodeAtInstant
     :members: