From e952fff01057eae65de5de891d5c402573607269 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 10 May 2022 18:48:03 +0300 Subject: [PATCH 01/10] Update dependencies recommonmark is obsolete and has been replaced by myst-parser, which bundles docutils and parses Markdown tables natively, removing the need for these extensions --- requirements.txt | 10 ++++------ source/conf.py | 11 +++-------- 2 files changed, 7 insertions(+), 14 deletions(-) diff --git a/requirements.txt b/requirements.txt index de366fca..ff928bf7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,8 +1,6 @@ --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==4.5.0 +sphinx_argparse==0.3.1 diff --git a/source/conf.py b/source/conf.py index 6935c798..a3a5db6d 100644 --- a/source/conf.py +++ b/source/conf.py @@ -4,7 +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 @@ -17,6 +16,7 @@ extensions = [ 'guzzle_sphinx_theme', + 'myst_parser', 'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.doctest', @@ -27,7 +27,6 @@ 'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx.ext.viewcode', - 'sphinx_markdown_tables', 'sphinxarg.ext', ] @@ -36,10 +35,6 @@ "python": ("https://docs.python.org/3/", None), } -source_parsers = { - '.md': CommonMarkParser, -} - source_suffix = ['.rst', '.md'] master_doc = 'summary' @@ -76,6 +71,6 @@ def setup(app): '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.add_css_file('style.css') + app.add_js_file('scripts.js') app.connect("missing-reference", missing_reference) From e16967a6420b0351f91070a99ec22925015bc41a Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 10 May 2022 19:04:25 +0300 Subject: [PATCH 02/10] Remove link workaround from obsolete library --- README.md | 6 ------ source/static/scripts.js | 13 ------------- 2 files changed, 19 deletions(-) diff --git a/README.md b/README.md index a47988cc..810ca7a4 100644 --- a/README.md +++ b/README.md @@ -80,9 +80,3 @@ 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) diff --git a/source/static/scripts.js b/source/static/scripts.js index 93e1c654..d97213f5 100644 --- a/source/static/scripts.js +++ b/source/static/scripts.js @@ -23,19 +23,6 @@ $(document).ready(function() { $('a[href^="https://"], a[href^="http://"]').attr("target", "_blank"); // Make all external links open in a new Window - // Internal docs containing an anchor are wrongly transpiled to an absolute link starting by '/'. This causes dead links when we serve under openfisca.org/doc. The following manually fix these links in JS. This could be avoided if we served on doc.openfisca.org - $( "a[href^='/']" ).attr("href", - function( _, href ) { - return getPathName() + href; - } - ); - - $( "img[src^='/']" ).attr("src", - function( _, src ) { - return getPathName() + src; - } - ); - // Activate action button tooltip $('.actionbutton').tooltip() }); From 0d1136af23efa77003576d7471705f76866a89b4 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 10 May 2022 19:04:55 +0300 Subject: [PATCH 03/10] Remove AutoStructify from obsolete package --- source/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/conf.py b/source/conf.py index a3a5db6d..26af9099 100644 --- a/source/conf.py +++ b/source/conf.py @@ -4,7 +4,6 @@ # # Full list of Sphinx options is available at http://www.sphinx-doc.org/en/master/config -from recommonmark.transform import AutoStructify import guzzle_sphinx_theme # -- Project information ----------------------------------------------------- @@ -70,7 +69,6 @@ def setup(app): '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_css_file('style.css') app.add_js_file('scripts.js') app.connect("missing-reference", missing_reference) From 039fbfbf64412fb5ce8d45fd9dbf22791d854772 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 10 May 2022 19:15:29 +0300 Subject: [PATCH 04/10] Fix inconsistent title hierarchy --- source/coding-the-legislation/reforms.md | 1 - source/key-concepts/person,_entities,_role.md | 5 ++++- source/key-concepts/reforms.md | 2 +- source/key-concepts/simulation.md | 6 +++--- source/key-concepts/tax_and_benefit_system.md | 4 ++-- source/key-concepts/variables.md | 6 +++--- source/simulate/replicate-simulation-inputs.md | 8 ++++---- 7 files changed, 17 insertions(+), 15 deletions(-) diff --git a/source/coding-the-legislation/reforms.md b/source/coding-the-legislation/reforms.md index 1361b20a..e24de4c4 100644 --- a/source/coding-the-legislation/reforms.md +++ b/source/coding-the-legislation/reforms.md @@ -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' diff --git a/source/key-concepts/person,_entities,_role.md b/source/key-concepts/person,_entities,_role.md index e9ea409d..df8c6515 100644 --- 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: diff --git a/source/key-concepts/reforms.md b/source/key-concepts/reforms.md index 2ede714f..3faee2fb 100644 --- a/source/key-concepts/reforms.md +++ b/source/key-concepts/reforms.md @@ -11,7 +11,7 @@ To use reforms or code your own ones, check the [reform documentation](../coding > Note that OpenFisca simulates only the *mechanics* of taxes and benefits, but doesn't take into account the retro-action of economic agents. For instance, you can estimate the increase of the households disposable income in case a universal basic income is introduced, but OpenFisca won't tell you anything about the consumption increase this policy may generate. -### Differences between reforms and extensions +## Differences between reforms and extensions Reforms are sometimes confused with another mechanism: [extensions](../contribute/extensions.md). These two mechanisms do not have the same purpose: diff --git a/source/key-concepts/simulation.md b/source/key-concepts/simulation.md index c2bb0e19..983db840 100644 --- a/source/key-concepts/simulation.md +++ b/source/key-concepts/simulation.md @@ -1,6 +1,6 @@ # Simulation, Computation -#### Simulation: the framework of computation +## Definition A *Simulation* is basically the OpenFisca frame for calculating taxes or benefits. @@ -10,7 +10,7 @@ To calculate any variable you need to create a *Simulation* from the *TaxBenefit It's possible to run many independent simulations using the same `TaxBenefitSystem`. -#### Computing variables +## Computing variables To compute taxes and benefits, you need to define on whom you want to do that and what you already know about those persons or groups of persons. This is what you will set as input data for your *Simulation*. @@ -20,7 +20,7 @@ Now all the settings are given to run computation of taxes or benefits. > For further information: see how to run a simulation in [this section](../simulate/run-simulation.md) and the following [tutorial](http://mybinder.org:/repo/openfisca/tutorial) "How to handle periods" -###### Application: how to calculate a variable +### Application: how to calculate a variable ```python # Calcul of the 'impot sur le revenu des personnes physiques' diff --git a/source/key-concepts/tax_and_benefit_system.md b/source/key-concepts/tax_and_benefit_system.md index b64b3409..258ee07a 100644 --- a/source/key-concepts/tax_and_benefit_system.md +++ b/source/key-concepts/tax_and_benefit_system.md @@ -1,6 +1,6 @@ # Tax and Benefit System -#### Definition +## Definition The tax and benefit system is the higher-level instance in OpenFisca. Its goal is to model the legislation of a country. @@ -15,7 +15,7 @@ This instance may host as many versions as there are countries in the world. Therefore you have to instantiate and use the version corresponding to your country of interest. -#### Application: how to call the Python module +### Application: how to call the Python module The system for France is currently the only one well implemented, so your first action should be: diff --git a/source/key-concepts/variables.md b/source/key-concepts/variables.md index fe2284c2..be30417f 100644 --- a/source/key-concepts/variables.md +++ b/source/key-concepts/variables.md @@ -9,11 +9,11 @@ For instance: * The amount of *income tax* a household has to pay in a year. * Whether a family is *living in Paris*, or not. -### Input variables +## Input variables Some variables can only be given as inputs of a simulation. For instance, the *birth date* of a person. -### Formulas +## Formulas Other variables can be calculated thanks to a **formula**. @@ -25,7 +25,7 @@ For instance: It is important to note that **all variables can be used as inputs**. This means that even if the *basic income* can be calculated from other variables, I can, for a given simulation, provide it as an input. Then, if another formula asks for the value of *basic income* for a month, the input value will be returned, and the *basic income* formula **won't be executed.** -### Default values +## Default values When OpenFisca is not able to calculate the value of a variable for a requested period, it returns a **default value**. diff --git a/source/simulate/replicate-simulation-inputs.md b/source/simulate/replicate-simulation-inputs.md index 986e879a..5b5c451b 100644 --- a/source/simulate/replicate-simulation-inputs.md +++ b/source/simulate/replicate-simulation-inputs.md @@ -1,4 +1,4 @@ -## Replicating a situation along axes +# Replicating a situation along axes So far we've seen two ways of populating a Simulation object with data: - either describe a [small population](./run-simulation.md#test-cases) with fine control over input variables and over the relationship between individuals and group entities; @@ -51,7 +51,7 @@ array([[ 0. , 0. , 0. , 0. ], We can see that, for the requested period, the variable `salary` **of the first individual in each group** is varying in increments from 0 to 3000. -### Targeting individuals +## Targeting individuals The control provided by an axis is fine-grained and targets one individual. If you wanted to set Javier's salary instead of Ari's, you could do so by providing the *index* of Javier in the original situation; since our indices are 0-based, this is 3: @@ -84,7 +84,7 @@ array([[ 0. , 0. , 0. , 0. ], Axes are particularly interesting when you want to chart how one variable relates to another, as in [this tutorial notebook](https://mybinder.org/v2/gh/openfisca/tutorial/master?filepath=notebooks/how_to_handle_axes.ipynb). -### Adding axes: parallel axes +## Adding axes: parallel axes We noted above that the "axes" are in fact an array of arrays, which allows us to use several axes at once : parallel **or** perpendicular axes. @@ -135,7 +135,7 @@ array([[ 0. , 0. , 0. , 0. ], For this to work, the `count` values of parallel axes must be the same. An error will be raised if they are different. -### Adding axes: perpendicular axes +## Adding axes: perpendicular axes Sets of axes in the outer array are "perpendicular", that is, they result in independent variation. For instance, we might have: From e13dbdf4d620f61a545c24e7c1aac0f6fdab6de7 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Wed, 25 May 2022 17:34:36 +0200 Subject: [PATCH 05/10] Update toctree syntax See https://github.com/readthedocs/recommonmark/issues/221#issuecomment-820962823 --- source/coding-the-legislation/index.md | 30 ++++++++--------- source/contribute/index.md | 27 ++++++++------- source/installation/index.md | 15 ++++----- source/key-concepts/index.md | 19 +++++------ source/openfisca-python-api/index.md | 46 +++++++++++--------------- source/openfisca-web-api/index.md | 15 ++++----- source/simulate/index.md | 15 ++++----- 7 files changed, 77 insertions(+), 90 deletions(-) diff --git a/source/coding-the-legislation/index.md b/source/coding-the-legislation/index.md index fbfe3908..b8778362 100644 --- a/source/coding-the-legislation/index.md +++ b/source/coding-the-legislation/index.md @@ -1,21 +1,19 @@ # 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/contribute/index.md b/source/contribute/index.md index 72fddcfd..a326cf1d 100644 --- a/source/contribute/index.md +++ b/source/contribute/index.md @@ -1,19 +1,18 @@ # 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/installation/index.md b/source/installation/index.md index ffa3106b..7d4ce96b 100644 --- a/source/installation/index.md +++ b/source/installation/index.md @@ -1,14 +1,13 @@ # 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 index 4e9ab8d6..df581dc4 100644 --- a/source/key-concepts/index.md +++ b/source/key-concepts/index.md @@ -1,16 +1,15 @@ # 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/openfisca-python-api/index.md b/source/openfisca-python-api/index.md index ecedfdc9..01ef4be9 100644 --- a/source/openfisca-python-api/index.md +++ b/source/openfisca-python-api/index.md @@ -3,34 +3,28 @@ Modules: -```eval_rst -.. toctree:: - :maxdepth: 1 - - commons - tax-benefit-system - variables - parameters - reforms - simulations - entities - populations - test_runner - tracer - enum_array - holder - simulation_generator - periods - errors - types +```{toctree} +commons +tax-benefit-system +variables +parameters +reforms +simulations +entities +populations +test_runner +tracer +enum_array +holder +simulation_generator +periods +errors +types ``` Scripts: -```eval_rst -.. toctree:: - :maxdepth: 1 - - openfisca_test - openfisca_serve +```{toctree} +openfisca_test +openfisca_serve ``` diff --git a/source/openfisca-web-api/index.md b/source/openfisca-web-api/index.md index f9d2a040..86fa9884 100644 --- a/source/openfisca-web-api/index.md +++ b/source/openfisca-web-api/index.md @@ -1,13 +1,12 @@ # OpenFisca Web API -```eval_rst -.. toctree:: - :hidden: - - endpoints - input-output-data - trace-simulation - config-openapi +```{toctree} +:hidden: + +endpoints +input-output-data +trace-simulation +config-openapi ``` OpenFisca provides a web API package, compatible with all country packages. diff --git a/source/simulate/index.md b/source/simulate/index.md index 215e7b13..7bcdd631 100644 --- a/source/simulate/index.md +++ b/source/simulate/index.md @@ -1,13 +1,12 @@ # Running a simulation -```eval_rst -.. toctree:: - :hidden: - - run-simulation - analyse-simulation - replicate-simulation-inputs - profile-simulation +```{toctree} +:hidden: + +run-simulation +analyse-simulation +replicate-simulation-inputs +profile-simulation ``` To calculate Tax and Benefit System variables on people's situations, you need to create and run a new *Simulation*. From c3a3ade3450b951da0c62ce1e8bc371941b5d822 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Wed, 25 May 2022 17:57:15 +0200 Subject: [PATCH 06/10] Generate anchor links --- source/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/conf.py b/source/conf.py index 26af9099..a8e417b3 100644 --- a/source/conf.py +++ b/source/conf.py @@ -54,6 +54,8 @@ 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'] From 638df28421a75984ca2467a15a6b33300258a6f2 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Wed, 25 May 2022 18:03:45 +0200 Subject: [PATCH 07/10] Update dead internal links --- .../coding-the-legislation/10_basic_example.md | 2 +- source/coding-the-legislation/35_periods.md | 2 +- .../40_legislation_evolutions.md | 4 ++-- source/coding-the-legislation/reforms.md | 6 +++--- .../writing_yaml_tests.md | 2 +- source/contribute/extensions.md | 2 +- source/index.md | 18 +++++++++--------- source/licence.md | 2 +- source/simulate/analyse-simulation.md | 2 +- 9 files changed, 20 insertions(+), 20 deletions(-) diff --git a/source/coding-the-legislation/10_basic_example.md b/source/coding-the-legislation/10_basic_example.md index d3121dfa..22105e32 100644 --- 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 index ea0a595e..a36b4984 100644 --- 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 index d60fc625..cc74043b 100644 --- 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/reforms.md b/source/coding-the-legislation/reforms.md index e24de4c4..d3f53ab4 100644 --- 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 @@ -30,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. @@ -89,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 index 2ce84430..49ac2d49 100644 --- 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/contribute/extensions.md b/source/contribute/extensions.md index c23decc4..632568c5 100644 --- 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/index.md b/source/index.md index 6d9e9d71..b4b028b5 100644 --- a/source/index.md +++ b/source/index.md @@ -1,6 +1,6 @@ # 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/licence.md b/source/licence.md index d5fe5a82..ac39782b 100644 --- a/source/licence.md +++ b/source/licence.md @@ -55,7 +55,7 @@ Please make sure to update the destination of the source code link if you use a ## Changes -If you modify or extend OpenFisca, you are [legally required](https://choosealicense.com/licenses/agpl-3.0/) to make those changes available to the community. The easiest way to do it is to publish your fork of the core package, and of any country package, extension or reform, on a source hosting platform such as GitHub, and to [notify](./contribute/) the core team of this publication. +If you modify or extend OpenFisca, you are [legally required](https://choosealicense.com/licenses/agpl-3.0/) to make those changes available to the community. The easiest way to do it is to publish your fork of the core package, and of any country package, extension or reform, on a source hosting platform such as GitHub, and to notify the core team of this publication. You can read [this analysis](https://softwareengineering.stackexchange.com/questions/107883/agpl-what-you-can-do-and-what-you-cant/314908/) to get more insight on what you can and can't do with APGL licensed software. diff --git a/source/simulate/analyse-simulation.md b/source/simulate/analyse-simulation.md index ec226781..00b0c8a5 100644 --- a/source/simulate/analyse-simulation.md +++ b/source/simulate/analyse-simulation.md @@ -38,7 +38,7 @@ housing_allowance = simulation.calculate('housing_allowance', '2011-01') simulation.tracer.print_computation_log() ``` -> For more information on the `tracer` methods, see this [Tracer class interface](../../openfisca-python-api/tracer.html) +> For more information on the `tracer` methods, see this [Tracer class interface](../../openfisca-python-api/tracer) ## Analysing simulation steps From f0b8856f76cd08e5b4b61693a85dc9465d9b25a7 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Wed, 25 May 2022 17:57:29 +0200 Subject: [PATCH 08/10] Unify quote styles in config --- source/conf.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/conf.py b/source/conf.py index a8e417b3..fec94c53 100644 --- a/source/conf.py +++ b/source/conf.py @@ -30,8 +30,8 @@ ] 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_suffix = ['.rst', '.md'] @@ -46,8 +46,8 @@ 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'] @@ -62,7 +62,7 @@ def missing_reference(app, env, node, contnode): - if node["reftype"] == "class" and node["reftarget"] == "NDArray": + if node['reftype'] == 'class' and node['reftarget'] == 'NDArray': return contnode @@ -73,4 +73,4 @@ def setup(app): }, True) app.add_css_file('style.css') app.add_js_file('scripts.js') - app.connect("missing-reference", missing_reference) + app.connect('missing-reference', missing_reference) From 65c96ee948a21892fc6851781c182e592c7886d2 Mon Sep 17 00:00:00 2001 From: Mauko Date: Mon, 30 May 2022 18:48:10 +0200 Subject: [PATCH 09/10] Add plugin to parse types --- README.md | 2 +- requirements.txt | 1 + source/conf.py | 4 ++-- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 810ca7a4..bd823f5c 100644 --- a/README.md +++ b/README.md @@ -79,4 +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! 🙌 +That's it! 🙌 \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index ff928bf7..cb3012bc 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,5 +2,6 @@ guzzle_sphinx_theme==0.7.11 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/conf.py b/source/conf.py index fec94c53..a98ad75c 100644 --- a/source/conf.py +++ b/source/conf.py @@ -26,6 +26,7 @@ 'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx.ext.viewcode', + 'sphinx_autodoc_typehints', 'sphinxarg.ext', ] @@ -62,10 +63,9 @@ 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'), From f344ea0b6ddc897724a7c73b1a9c9fcaa4a8b03b Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Thu, 16 Jun 2022 19:38:29 +0200 Subject: [PATCH 10/10] Deactivate type checks in documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Switch off “nitpicky” Sphinx option Fix otherwise impossible to fix “py:obj reference target not found” error --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 9738865f..2b5dd6c1 100644 --- 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: