openfisca · MattiSG · Jun 17, 2022 · May 10, 2022 · May 10, 2022 · May 10, 2022
diff --git a/Makefile b/Makefile
@@ -20,7 +20,7 @@ install:
 
 # Test the doc.
 test:
-	@${MAKE} dummy SPHINXOPTS="-n -q -W"
+	@${MAKE} dummy SPHINXOPTS="-q -W"
 
 # Serve the documentation in dev mode.
 dev:

diff --git a/README.md b/README.md
@@ -79,10 +79,4 @@ 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
-
-`recommonmark`, the library we use to include Markdown-written pages into the Sphinx-generated documentation, seems to have trouble correctly processing links. The current workarounds are:
-- Adding an extra `../` to links in Markdown-written pages pointing towards the rST-written pages
-- Dynamically rewriting some links [in Javascript](./source/static/scripts.js)
+That's it! 🙌
diff --git a/requirements.txt b/requirements.txt
@@ -1,8 +1,7 @@
 --editable git+https://github.com/openfisca/openfisca-core.git@master#egg=OpenFisca-Core[dev]
-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.1
-sphinx_argparse==0.2.5
+myst-parser==0.17.2
+sphinx-autobuild==2021.3.14
+sphinx-autodoc-typehints==1.18.1
+Sphinx==4.5.0
+sphinx_argparse==0.3.1
diff --git a/source/coding-the-legislation/10_basic_example.md b/source/coding-the-legislation/10_basic_example.md
@@ -31,7 +31,7 @@ so the actual type of data may be slightly different from the built-in Python on
 Available types are :
     - `bool`: boolean
     - `date`: date
-    - `Enum`: discrete value (from an enumerable). [See details](20_input_variables.md#advanced-example-enumerations-enum) in the next section.
+    - `Enum`: discrete value (from an enumerable). [See details](20_input_variables.md) in the next section.
     - `float`: float (Note that to reduce memory usage, float are stored on 32 bits using NumPy's `float32`)
     - `int`: integer
     - `str`: string

diff --git a/source/coding-the-legislation/35_periods.md b/source/coding-the-legislation/35_periods.md
@@ -161,7 +161,7 @@ You can generate any period with the following properties and methods:
 | `period.start.period('year', n)`  | n-year-long period starting a the same time than `period`    |
 | `period.start.period('month', n)` | n-month-long period starting a the same time than `period`   |
 
-You can find more information on the `Period` object in the [reference documentation]() (_not available yet_)
+You can find more information on the `Period` object in the [reference documentation](../openfisca-python-api/periods).
 
 
 ## Automatically process variable inputs defined for periods not matching the `definition_period`

diff --git a/source/coding-the-legislation/40_legislation_evolutions.md b/source/coding-the-legislation/40_legislation_evolutions.md
@@ -51,7 +51,7 @@ After this change, in a formula:
 - `parameters('2017-01').taxes.salary.rate` is `0.3`
 - `parameters('2022-01').taxes.salary.rate` is `0.3`
 
-[Read more about how to code parameters](./legislation_parameters.md#parameters-and-time).
+[Read more about how to code parameters](./legislation_parameters.md).
 
 ## Formula evolution
 
@@ -90,7 +90,7 @@ Formula naming rules:
   - For instance, `formula_2017` is equivalent to `formula_2017_01_01`.
 - If no date is specified for a formula, OpenFisca will consider that this formula has been active since the dawn of time (or more precisely, since `0001-01-01`, as Python does not handle B.C. dates).
   - For instance, `formula` is active on `2010`.
-- A formula is active until another formula, starting later, becomes active and replaces it (or until the variable `end` date is reached, as we'll see further down in the [Variable end](#variable-end) section).
+- A formula is active until another formula, starting later, becomes active and replaces it (or until the [variable `end` date](#ending-a-variable-at-a-specific-date) is reached).
   - For instance, `formula` is active until `2016-12-31` (included). On the day after, `2017-01-01`, `formula_2017` becomes active, and `formula` becomes inactive.
 
 

diff --git a/source/coding-the-legislation/index.md b/source/coding-the-legislation/index.md
@@ -1,21 +1,19 @@
 # <i class="fas fa-code"></i> From law to code
 
-```eval_rst
-.. toctree::
-   :hidden:
-
-   10_basic_example
-   20_input_variables
-   25_vectorial_computing
-   35_periods
-   40_legislation_evolutions
-   50_entities
-   reforms
-   inferences
-   writing_yaml_tests
-   legislation_parameters
-   bootstrapping_a_new_country_package
-
+```{toctree}
+:hidden:
+
+10_basic_example
+20_input_variables
+25_vectorial_computing
+35_periods
+40_legislation_evolutions
+50_entities
+reforms
+inferences
+writing_yaml_tests
+legislation_parameters
+bootstrapping_a_new_country_package
 ```
 
 Now let's think practical. The following tutorial and documentation offer you an overview of OpenFisca principles.

diff --git a/source/coding-the-legislation/reforms.md b/source/coding-the-legislation/reforms.md
@@ -2,7 +2,7 @@
 
 A [reform](../key-concepts/reforms.md) is a set of modifications to be applied to a tax and benefit system, usually to study the quantitative impact of a possible change of the law.
 
-> See the reference documentation of the class [Reform](../../openfisca-python-api/reforms.html).
+> See the reference documentation of the class [Reform](../../openfisca-python-api/reforms).
 
 
 ## Writing a reform
@@ -12,7 +12,6 @@ Let's for instance assume that we want to simulate the effect of a reform that c
 We would write such a reform this way:
 
 ```py
-
 class income_tax(Variable):
     entity = Household
     label = u'Alternative formula to calculate the income tax, under experimentation'
@@ -31,7 +30,7 @@ A `Reform` **must** define an `apply()` method that describes all the modificati
 
 > Note that the reference tax and benefit system won't be modified. The `apply()` function will be applied to a copy of the tax and benefit system.
 
-All the [methods](../../openfisca-python-api/tax-benefit-system.html) used to build a tax and benefit system can also be used to reform it.
+All the [methods](../../openfisca-python-api/tax-benefit-system) used to build a tax and benefit system can also be used to reform it.
 
 A reform that modifies a formula (such as our `income_tax_reform` example) is called a *structural reform*. It redefines the way a variable is calculated.
 
@@ -90,7 +89,7 @@ class some_reform(Reform):
 
 #### Add new parameters dynamically
 
-In some cases, loading new parameters from YAML files is not practical. For example, you may want to add parameters from values computed dynamically. In such cases you can use the python objects defined in the [parameters module](../../openfisca-python-api/parameters.html)
+In some cases, loading new parameters from YAML files is not practical. For example, you may want to add parameters from values computed dynamically. In such cases you can use the python objects defined in the [parameters module](../../openfisca-python-api/parameters)
 :
 
 ```python

diff --git a/source/coding-the-legislation/writing_yaml_tests.md b/source/coding-the-legislation/writing_yaml_tests.md
@@ -183,7 +183,7 @@ You can find examples of YAML tests of tax and benefit systems with reforms appl
 
 ## Running a test
 
-To run YAML tests, use the command line tool `openfisca test`, documented [here](../../openfisca-python-api/openfisca_test.html):
+To run YAML tests, use the command line tool `openfisca test`, documented [here](../../openfisca-python-api/openfisca_test):
 
 ```sh
 openfisca test path/to/file.yaml

diff --git a/source/conf.py b/source/conf.py
@@ -4,8 +4,6 @@
 #
 # Full list of Sphinx options is available at http://www.sphinx-doc.org/en/master/config
 
-from recommonmark.parser import CommonMarkParser
-from recommonmark.transform import AutoStructify
 import guzzle_sphinx_theme
 
 # -- Project information -----------------------------------------------------
@@ -17,6 +15,7 @@
 
 extensions = [
     'guzzle_sphinx_theme',
+    'myst_parser',
     'sphinx.ext.autodoc',
     'sphinx.ext.coverage',
     'sphinx.ext.doctest',
@@ -27,19 +26,15 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
-    'sphinx_markdown_tables',
+    'sphinx_autodoc_typehints',
     'sphinxarg.ext',
 ]
 
 intersphinx_mapping = {
-    "numpy": ("https://numpy.org/doc/stable/", None),
-    "python": ("https://docs.python.org/3/", None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'python': ('https://docs.python.org/3/', None),
     }
 
-source_parsers = {
-    '.md': CommonMarkParser,
-}
-
 source_suffix = ['.rst', '.md']
 
 master_doc = 'summary'
@@ -52,30 +47,30 @@
 html_theme = 'guzzle_sphinx_theme'
 
 html_theme_options = {
-    "project_nav_name": "OpenFisca",
-    "homepage": "index",  # Different than the master doc
+    'project_nav_name': 'OpenFisca',
+    'homepage': 'index',  # Different than the master doc
 }
 
 html_static_path = ['static']
 templates_path = ['_templates']
 html_sidebars = {'**': ['sidebar.html']}
 
+myst_heading_anchors = 5  # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors
+
 github_doc_root = 'https://github.com/openfisca/openfisca-doc/tree/master/'
 
 suppress_warnings = ['image.nonlocal_uri']
 
 
 def missing_reference(app, env, node, contnode):
-    if node["reftype"] == "class" and node["reftarget"] == "NDArray":
+    if node['reftype'] == 'class' and node['reftarget'].startswith('nptyping'):
         return contnode
 
-
 def setup(app):
     app.add_config_value('recommonmark_config', {
         'url_resolver': lambda url: url.replace('.md', '.html'),
         'enable_auto_toc_tree': False
         }, True)
-    app.add_transform(AutoStructify)  # Manage avanced Markdown files with AutoStructify
-    app.add_stylesheet('style.css')
-    app.add_javascript('scripts.js')
-    app.connect("missing-reference", missing_reference)
+    app.add_css_file('style.css')
+    app.add_js_file('scripts.js')
+    app.connect('missing-reference', missing_reference)
diff --git a/source/contribute/extensions.md b/source/contribute/extensions.md
@@ -6,7 +6,7 @@ They are for instance used to code local prestations.
 
 > Extensions are sometimes confused with another mechanism: reforms. [Read more about their respective uses](../key-concepts/reforms.md#differences-between-reforms-and-extensions).
 
-Extensions can be manually loaded to a tax and benefit system using the [load_extension](../../openfisca-python-api/tax-benefit-system.html#openfisca_core.taxbenefitsystems.TaxBenefitSystem.load_extension) method.
+Extensions can be manually loaded to a tax and benefit system using the [load_extension](../../openfisca-python-api/tax-benefit-system) method.
 
 ## Extension architecture
 

diff --git a/source/contribute/index.md b/source/contribute/index.md
@@ -1,19 +1,18 @@
 # <i class="fas fa-users"></i> Contribute
 
-```eval_rst
-.. toctree::
-   :hidden:
-
-   guidelines
-   language
-   commit-messages
-   variables-naming
-   semver
-   documentation
-   extensions
-   developer-guide
-   tests
-   release-process
+```{toctree}
+:hidden:
+
+guidelines
+language
+commit-messages
+variables-naming
+semver
+documentation
+extensions
+developer-guide
+tests
+release-process
 ```
 
 OpenFisca is a free software project and contributors are very welcome!

diff --git a/source/index.md b/source/index.md
@@ -1,6 +1,6 @@
 # <i class="fas fa-home"></i> Before you start
 
-[OpenFisca](https://www.openfisca.org) is an open source platform to write rules as code.
+[OpenFisca](https://openfisca.org) is an open source platform to write rules as code.
 
 Describe your tax and benefit system, provide a situation as input (i.e income), ask for a calculation as output (i.e. income tax), and get your results.
 
@@ -15,18 +15,18 @@ Describe your tax and benefit system, provide a situation as input (i.e income),
 With OpenFisca, you can:
 * Use an existing tax and benefit system (see the [list of systems already built](https://openfisca.org/en/countries/))
 * [Build a new tax and benefit system](coding-the-legislation/bootstrapping_a_new_country_package.md) if it doesn’t exist already
-* [Contribute](contribute/index.html) to an existing system by adding or improving elements of the legislation
+* [Contribute](contribute/index.md) to an existing system by adding or improving elements of the legislation
 
 How to turn legal code into Python code?
 
 * First, identify some legislation that can be expressed as an arithmetic operation.
-* Then, try to translate them into [formulas, variables, parameters, etc.](coding-the-legislation/index.html)
-* You can even [build some tests](coding-the-legislation/writing_yaml_tests.html) to verify your implementation of the law.
+* Then, try to translate them into [formulas, variables, parameters, etc.](coding-the-legislation/index.md)
+* You can even [build some tests](coding-the-legislation/writing_yaml_tests.md) to verify your implementation of the law.
 * Lost? You are not the first one to go through that! Join us [here](https://forms.gle/kA6bijAJBL4kJz4e8) to ask the community for some hints and to celebrate your progress.
 
 ### 2 - Choose what kind of input data you need
 
-With OpenFisca, you can [run a simulation](simulate/index.html) on a single situation or on a whole population. OpenFisca doesn’t provide any data, the data you need depends on what you’re trying to calculate.
+With OpenFisca, you can [run a simulation](simulate/index.md) on a single situation or on a whole population. OpenFisca doesn’t provide any data, the data you need depends on what you’re trying to calculate.
 
 Do you want to help users find their eligibility for a social benefit in your country? Go and ask the users of your application to give you the income and demographic information you need in order to provide them with an answer (please do not forget to be GDPR compliant!).
 
@@ -36,18 +36,18 @@ Are you trying to simulate the impact of a new housing tax on behalf of the OECD
 
 There are two ways to use your results:
 
-* If you want to build a web service with the results of your simulation, you’ll definitely want to take a look at our [web API](openfisca-web-api/index.html).
+* If you want to build a web service with the results of your simulation, you’ll definitely want to take a look at our [web API](openfisca-web-api/index.md).
 
-* If you’re working on your thesis, you’ll rather use our [Python API](openfisca-python-api/index.html).
+* If you’re working on your thesis, you’ll rather use our [Python API](openfisca-python-api/index.md).
 
 Also, there are tons of libraries to help you illustrate your results ([plot.ly](https://plot.ly) for instance, will get you those nice charts you’ve seen elsewhere).
 
-Please make sure you read our [licence information](licence.html) before using results based on OpenFisca.
+Please make sure you read our [licence information](licence.md) before using results based on OpenFisca.
 
 ## Things OpenFisca won’t do for you:
 
 * Behaviour-based analysis. OpenFisca is a static micro-simulation model, so it will provide you with results “as-of-tomorrow” (i.e. a new tax bracket won’t affect consumption).
-* OpenFisca is contributive: if the legislation you need is not described yet, you’re the best person to add it (take a look at our [contribution guidelines](contribute/index.html)).
+* OpenFisca is contributive: if the legislation you need is not described yet, you’re the best person to add it (take a look at our [contribution guidelines](contribute/index.md)).
 * OpenFisca shines in dealing with numbers: Enumerated values are a later addition, and support for serving/testing string values is not built in.
 
 ## Find inspiration

diff --git a/source/installation/index.md b/source/installation/index.md
@@ -1,14 +1,13 @@
 # <i class="fas fa-cogs"></i> Installation
 
-```eval_rst
-.. toctree::
-   :hidden:
+```{toctree}
+:hidden:
 
-   howto-web-no-local-install
-   howto_docker
-   offline-environment
-   windows-no-admin
-   test_situations
+howto-web-no-local-install
+howto_docker
+offline-environment
+windows-no-admin
+test_situations
 ```
 
 As the OpenFisca community becomes larger, issues that only affect a small percentage of users arise.

diff --git a/source/key-concepts/index.md b/source/key-concepts/index.md
@@ -1,16 +1,15 @@
 # <i class="fas fa-dice-d6"></i> Key concepts
 
-```eval_rst
-.. toctree::
-   :hidden:
+```{toctree}
+:hidden:
 
-   tax_and_benefit_system
-   variables
-   parameters
-   person,_entities,_role
-   periodsinstants
-   simulation
-   reforms
+tax_and_benefit_system
+variables
+parameters
+person,_entities,_role
+periodsinstants
+simulation
+reforms
 ```
 
 This section presents the key concepts required to have a good understanding of OpenFisca, without being too technical.

diff --git a/source/key-concepts/person,_entities,_role.md b/source/key-concepts/person,_entities,_role.md
@@ -3,11 +3,13 @@
 Taxes and benefits can be calculated for different entities: persons, household, companies, etc.
 
 ## Person
+
 Some openfisca variables are defined for a *person*.
 
 Example: a ["salary"](https://fr.openfisca.org/legislation/salaire_net) is defined as the individual level.
 
 ##  Group entities
+
 *Group entities* are clusters of *persons* such as the family, the household or the company.
 A tax and benefit system can define several entities and specifies each time which tax and benefit applies to which entity.
 
@@ -18,7 +20,8 @@ In France the legislation has these *group entities*:
 
 Example: the  ["local tax"](https://fr.openfisca.org/legislation/taxe_habitation) is calculated over the `"menages"`.
 
-###### Roles
+### Roles
+
 Each person related to a *group entity* has a *role* inside this entity.
 
 The *roles* are: