From a3b5b6f806ef9a42e189ebc5cd1f898f7871848a Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Mon, 30 Aug 2021 16:35:18 +0200 Subject: [PATCH 01/40] Add flake8-rst-docstrings To check for any invalid rst syntax that could break the documentation. --- setup.py | 1 + 1 file changed, 1 insertion(+) diff --git a/setup.py b/setup.py index eb83761916..d67113a6fd 100644 --- a/setup.py +++ b/setup.py @@ -27,6 +27,7 @@ 'flake8 >= 3.9.0, < 4.0.0', 'flake8-bugbear >= 19.3.0, < 20.0.0', 'flake8-print >= 3.1.0, < 4.0.0', + 'flake8-rst-docstrings < 1.0.0', 'pytest-cov >= 2.6.1, < 3.0.0', 'mypy >= 0.701, < 0.800', 'openfisca-country-template >= 3.10.0, < 4.0.0', From 04f251311d5742b4059c2ca85fb1adc6ef257b1d Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 19:28:54 +0200 Subject: [PATCH 02/40] Add task to test the doc --- .gitignore | 1 + Makefile | 14 +++++++++++++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 06bfe7ec27..4b56efc6da 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ .vscode/ build/ dist/ +doc/ *.egg-info *.mo *.pyc diff --git a/Makefile b/Makefile index 30a0578f0d..8e25ac2e77 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ doc = sed -n "/^$1/ { x ; p ; } ; s/\#\#/[⚙]/ ; s/\./.../ ; x" ${MAKEFILE_LIST} -## Same as `make test. +## Same as `make test`. all: test ## Install project dependencies. @@ -54,6 +54,18 @@ test: clean check-syntax-errors check-style check-types @$(call doc,$@:) @env PYTEST_ADDOPTS="${PYTEST_ADDOPTS} --cov=openfisca_core" pytest +test.doc: + @[ ! -d doc ] \ + && git clone https://github.com/openfisca/openfisca-doc doc \ + || { cd doc ; git pull 2> /dev/null ; } + + @[ $$(pip freeze | grep -c "Sphinx") -eq 0 ] \ + && pip install -r doc/requirements.txt --use-deprecated=legacy-resolver \ + && pip install --editable .[dev] --upgrade --use-deprecated=legacy-resolver \ + || : + + @sphinx-build -M dummy doc/source doc/build -a -n -T -W 1> /dev/null + ## Serve the openfisca Web API. api: @$(call doc,$@:) From 9dc68eac7f6fbedb1b13d8312fff5d897bdede70 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Mon, 30 Aug 2021 16:42:19 +0200 Subject: [PATCH 03/40] Whitelist the attribute directive --- openfisca_core/parameters/parameter.py | 2 +- .../taxbenefitsystems/tax_benefit_system.py | 2 +- openfisca_core/variables/variable.py | 36 +++++++++---------- setup.cfg | 9 ++--- 4 files changed, 25 insertions(+), 24 deletions(-) diff --git a/openfisca_core/parameters/parameter.py b/openfisca_core/parameters/parameter.py index 85d367ae67..62fd3f6766 100644 --- a/openfisca_core/parameters/parameter.py +++ b/openfisca_core/parameters/parameter.py @@ -34,7 +34,7 @@ class Parameter(AtInstantLike): } }) - .. py:attribute:: values_list + .. attribute:: values_list List of the values, in reverse chronological order """ diff --git a/openfisca_core/taxbenefitsystems/tax_benefit_system.py b/openfisca_core/taxbenefitsystems/tax_benefit_system.py index 6ca8443492..44fffd6a06 100644 --- a/openfisca_core/taxbenefitsystems/tax_benefit_system.py +++ b/openfisca_core/taxbenefitsystems/tax_benefit_system.py @@ -31,7 +31,7 @@ class TaxBenefitSystem: :param string parameters: Directory containing the YAML parameter files. - .. py:attribute:: parameters + .. attribute:: parameters :any:`ParameterNode` containing the legislation parameters """ diff --git a/openfisca_core/variables/variable.py b/openfisca_core/variables/variable.py index 1be200b4be..0cc280a267 100644 --- a/openfisca_core/variables/variable.py +++ b/openfisca_core/variables/variable.py @@ -19,77 +19,77 @@ class Variable: Main attributes: - .. py:attribute:: name + .. attribute:: name Name of the variable - .. py:attribute:: value_type + .. attribute:: value_type The value type of the variable. Possible value types in OpenFisca are ``int`` ``float`` ``bool`` ``str`` ``date`` and ``Enum``. - .. py:attribute:: entity + .. attribute:: entity `Entity `_ the variable is defined for. For instance : ``Person``, ``Household``. - .. py:attribute:: definition_period + .. attribute:: definition_period `Period `_ the variable is defined for. Possible value: ``MONTH``, ``YEAR``, ``ETERNITY``. - .. py:attribute:: formulas + .. attribute:: formulas Formulas used to calculate the variable - .. py:attribute:: label + .. attribute:: label Description of the variable - .. py:attribute:: reference + .. attribute:: reference Legislative reference describing the variable. - .. py:attribute:: default_value + .. attribute:: default_value `Default value `_ of the variable. Secondary attributes: - .. py:attribute:: baseline_variable + .. attribute:: baseline_variable If the variable has been introduced in a `reform `_ to replace another variable, baseline_variable is the replaced variable. - .. py:attribute:: dtype + .. attribute:: dtype Numpy `dtype `_ used under the hood for the variable. - .. py:attribute:: end + .. attribute:: end `Date `_ when the variable disappears from the legislation. - .. py:attribute:: is_neutralized + .. attribute:: is_neutralized True if the variable is neutralized. Neutralized variables never use their formula, and only return their default values when calculated. - .. py:attribute:: json_type + .. attribute:: json_type JSON type corresponding to the variable. - .. py:attribute:: max_length + .. attribute:: max_length If the value type of the variable is ``str``, max length of the string allowed. ``None`` if there is no limit. - .. py:attribute:: possible_values + .. attribute:: possible_values If the value type of the variable is ``Enum``, contains the values the variable can take. - .. py:attribute:: set_input + .. attribute:: set_input Function used to automatically process variable inputs defined for periods not matching the definition_period of the variable. See more on the `documentation `_. Possible values are ``set_input_dispatch_by_period``, ``set_input_divide_by_period``, or nothing. - .. py:attribute:: unit + .. attribute:: unit Free text field describing the unit of the variable. Only used as metadata. - .. py:attribute:: documentation + .. attribute:: documentation Free multilines text field describing the variable context and usage. """ diff --git a/setup.cfg b/setup.cfg index 8c18f3a892..c7b98bea30 100644 --- a/setup.cfg +++ b/setup.cfg @@ -5,10 +5,11 @@ ; W503/504: We break lines before binary operators (Knuth's style) [flake8] -hang-closing = true -ignore = E128,E251,F403,F405,E501,W503,W504 -in-place = true -rst-roles = any +hang-closing = true +ignore = E128,E251,F403,F405,E501,W503,W504 +in-place = true +rst-roles = any +rst-directives = any, attribute [tool:pytest] addopts = --showlocals --doctest-modules --disable-pytest-warnings From 26b1a25d22579e75e902b5a156f3c16fda0764b0 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Mon, 30 Aug 2021 16:43:53 +0200 Subject: [PATCH 04/40] Whitelist the class role --- setup.cfg | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/setup.cfg b/setup.cfg index c7b98bea30..6e106dae23 100644 --- a/setup.cfg +++ b/setup.cfg @@ -8,8 +8,8 @@ hang-closing = true ignore = E128,E251,F403,F405,E501,W503,W504 in-place = true -rst-roles = any -rst-directives = any, attribute +rst-roles = any, class +rst-directives = attribute [tool:pytest] addopts = --showlocals --doctest-modules --disable-pytest-warnings From f783ffd9f47c2cd9a6a705857ca215c1ee995d7f Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Mon, 30 Aug 2021 16:44:47 +0200 Subject: [PATCH 05/40] Whitelist the meth role --- setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 6e106dae23..9a59788226 100644 --- a/setup.cfg +++ b/setup.cfg @@ -8,7 +8,7 @@ hang-closing = true ignore = E128,E251,F403,F405,E501,W503,W504 in-place = true -rst-roles = any, class +rst-roles = any, class, meth rst-directives = attribute [tool:pytest] From 3255f0a94da9fc17754f0af1af2ce6df325c2c81 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Mon, 30 Aug 2021 16:46:19 +0200 Subject: [PATCH 06/40] Whitelist the obj role --- setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 9a59788226..8af5ffd758 100644 --- a/setup.cfg +++ b/setup.cfg @@ -8,7 +8,7 @@ hang-closing = true ignore = E128,E251,F403,F405,E501,W503,W504 in-place = true -rst-roles = any, class, meth +rst-roles = any, class, meth, obj rst-directives = attribute [tool:pytest] From f83f167dc037fd706342bd21af21c742efb708da Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Mon, 30 Aug 2021 16:47:02 +0200 Subject: [PATCH 07/40] Whitelist the exc role --- setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 8af5ffd758..4f98591eeb 100644 --- a/setup.cfg +++ b/setup.cfg @@ -8,7 +8,7 @@ hang-closing = true ignore = E128,E251,F403,F405,E501,W503,W504 in-place = true -rst-roles = any, class, meth, obj +rst-roles = any, class, exc, meth, obj rst-directives = attribute [tool:pytest] From 45dad350e6121372e3ba8ee194d3edd33d565845 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Mon, 30 Aug 2021 16:56:02 +0200 Subject: [PATCH 08/40] Fix invalid markdown in rst docstring --- tests/fixtures/appclient.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/tests/fixtures/appclient.py b/tests/fixtures/appclient.py index 32d9e71aee..a140e0f938 100644 --- a/tests/fixtures/appclient.py +++ b/tests/fixtures/appclient.py @@ -6,9 +6,12 @@ @pytest.fixture(scope="module") def test_client(tax_benefit_system): """ This module-scoped fixture creates an API client for the TBS defined in the `tax_benefit_system` - fixture. This `tax_benefit_system` is mutable, so you can add/update variables. Example: + fixture. This `tax_benefit_system` is mutable, so you can add/update variables. + + Example: + + .. code-block:: python - ``` from openfisca_country_template import entities from openfisca_core import periods from openfisca_core.variables import Variable @@ -23,7 +26,7 @@ class new_variable(Variable): tax_benefit_system.add_variable(new_variable) flask_app = app.create_app(tax_benefit_system) - ``` + """ # Create the test API client From cab2091eac0181305d2c7c87d66e4b7c833761ad Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Mon, 30 Aug 2021 17:02:44 +0200 Subject: [PATCH 09/40] Fix invalid rst --- tests/web_api/test_calculate.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/web_api/test_calculate.py b/tests/web_api/test_calculate.py index 5fb6d702b7..b3415810a7 100644 --- a/tests/web_api/test_calculate.py +++ b/tests/web_api/test_calculate.py @@ -346,7 +346,7 @@ def test_handle_period_mismatch_error(test_client): def test_gracefully_handle_unexpected_errors(test_client): """ Context - ======== + ======= Whenever an exception is raised by the calculation engine, the API will try to handle it and to provide a useful message to the user (4XX). When the @@ -359,7 +359,7 @@ def test_gracefully_handle_unexpected_errors(test_client): Calculate the housing tax due by Bill a thousand years ago. Expected behaviour - ======== + ================== In the `country-template`, Housing Tax is only defined from 2010 onwards. The calculation engine should therefore raise an exception `ParameterNotFound`. From 178c14eae3e77f1d5b078a8ab53b07cffa447531 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 19:29:37 +0200 Subject: [PATCH 10/40] Fix malformed table --- openfisca_core/tools/test_runner.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openfisca_core/tools/test_runner.py b/openfisca_core/tools/test_runner.py index f6833c74bb..edd34049e6 100644 --- a/openfisca_core/tools/test_runner.py +++ b/openfisca_core/tools/test_runner.py @@ -58,7 +58,7 @@ def run_tests(tax_benefit_system, paths, options = None): | Key | Type | Role | +===============================+===========+===========================================+ | verbose | ``bool`` | | - +-------------------------------+-----------+ See :any:`openfisca_test` options doc + + +-------------------------------+-----------+ See :any:`openfisca_test` options doc + | | name_filter | ``str`` | | +-------------------------------+-----------+-------------------------------------------+ From c2d475e6df4159cbe166a033d3d74e71bf651796 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 19:40:12 +0200 Subject: [PATCH 11/40] Fix reference to numpy in enums --- openfisca_core/indexed_enums/enum.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/openfisca_core/indexed_enums/enum.py b/openfisca_core/indexed_enums/enum.py index 97b9a285e4..3d9fc08447 100644 --- a/openfisca_core/indexed_enums/enum.py +++ b/openfisca_core/indexed_enums/enum.py @@ -5,7 +5,7 @@ import numpy -from openfisca_core.indexed_enums import config, EnumArray +from . import ENUM_ARRAY_DTYPE, EnumArray class Enum(enum.Enum): @@ -43,8 +43,8 @@ def encode( array into an :any:`EnumArray`. See :any:`EnumArray.decode` for decoding. - :param ndarray array: Array of string identifiers, or of enum items, to - encode. + :param numpy.ndarray array: Array of string identifiers, or of enum + items, to encode. :returns: An :any:`EnumArray` encoding the input array values. :rtype: :any:`EnumArray` @@ -72,7 +72,7 @@ def encode( array = numpy.select( [array == item.name for item in cls], [item.index for item in cls], - ).astype(config.ENUM_ARRAY_DTYPE) + ).astype(ENUM_ARRAY_DTYPE) # Enum items arrays elif isinstance(array, numpy.ndarray) and \ @@ -94,6 +94,6 @@ def encode( array = numpy.select( [array == item for item in cls], [item.index for item in cls], - ).astype(config.ENUM_ARRAY_DTYPE) + ).astype(ENUM_ARRAY_DTYPE) return EnumArray(array, cls) From fdbaf6e9556fbce8458d90080a66be637cfb16d6 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 19:55:42 +0200 Subject: [PATCH 12/40] Fix missing reference in simulations --- openfisca_core/simulations/simulation.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/openfisca_core/simulations/simulation.py b/openfisca_core/simulations/simulation.py index 9544925990..ca6e73f793 100644 --- a/openfisca_core/simulations/simulation.py +++ b/openfisca_core/simulations/simulation.py @@ -84,6 +84,8 @@ def data_storage_dir(self): # ----- Calculation methods ----- # def calculate(self, variable_name, period): + """Calculate ``variable_name`` for ``period``.""" + if period is not None and not isinstance(period, Period): period = periods.period(period) @@ -311,7 +313,7 @@ def get_array(self, variable_name, period): """ Return the value of ``variable_name`` for ``period``, if this value is alreay in the cache (if it has been set as an input or previously calculated). - Unlike :any:`calculate`, this method *does not* trigger calculations and *does not* use any formula. + Unlike :meth:`calculate`, this method *does not* trigger calculations and *does not* use any formula. """ if period is not None and not isinstance(period, Period): period = periods.period(period) @@ -319,7 +321,7 @@ def get_array(self, variable_name, period): def get_holder(self, variable_name): """ - Get the :any:`Holder` associated with the variable ``variable_name`` for the simulation + Get the :class:`~openfisca_core.holders.Holder` associated with the variable ``variable_name`` for the simulation """ return self.get_variable_population(variable_name).get_holder(variable_name) From d90b85912c7c679f0e0677435d35454771dfbc7a Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 20:30:55 +0200 Subject: [PATCH 13/40] Fix missing reference in test runner --- openfisca_core/simulations/simulation.py | 2 +- openfisca_core/tools/test_runner.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/openfisca_core/simulations/simulation.py b/openfisca_core/simulations/simulation.py index ca6e73f793..b120e06fe9 100644 --- a/openfisca_core/simulations/simulation.py +++ b/openfisca_core/simulations/simulation.py @@ -321,7 +321,7 @@ def get_array(self, variable_name, period): def get_holder(self, variable_name): """ - Get the :class:`~openfisca_core.holders.Holder` associated with the variable ``variable_name`` for the simulation + Get the :obj:`~openfisca_core.holders.Holder` associated with the variable ``variable_name`` for the simulation """ return self.get_variable_population(variable_name).get_holder(variable_name) diff --git a/openfisca_core/tools/test_runner.py b/openfisca_core/tools/test_runner.py index edd34049e6..30d783f169 100644 --- a/openfisca_core/tools/test_runner.py +++ b/openfisca_core/tools/test_runner.py @@ -44,7 +44,7 @@ def run_tests(tax_benefit_system, paths, options = None): If `path` is a directory, subdirectories will be recursively explored. - :param TaxBenefitSystem tax_benefit_system: the tax-benefit system to use to run the tests + :param openfisca_core.taxbenefitsystems.TaxBenefitSystem tax_benefit_system: the tax-benefit system to use to run the tests :param (str/list) paths: A path, or a list of paths, towards the files or directories containing the tests to run. If a path is a directory, subdirectories will be recursively explored. :param dict options: See more details below. From 2eadc1d72c08627f9ff0495cca6d679ae7a8ee1e Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 20:41:56 +0200 Subject: [PATCH 14/40] Fix missing reference in tax benefit systems --- openfisca_core/taxbenefitsystems/tax_benefit_system.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openfisca_core/taxbenefitsystems/tax_benefit_system.py b/openfisca_core/taxbenefitsystems/tax_benefit_system.py index 44fffd6a06..4ffee5a46c 100644 --- a/openfisca_core/taxbenefitsystems/tax_benefit_system.py +++ b/openfisca_core/taxbenefitsystems/tax_benefit_system.py @@ -33,7 +33,7 @@ class TaxBenefitSystem: .. attribute:: parameters - :any:`ParameterNode` containing the legislation parameters + :obj:`~openfisca_core.parameters.ParameterNode` containing the legislation parameters """ _base_tax_benefit_system = None _parameters_at_instant_cache = None From 2d71b50ba33811cdf90ec28a1b7b5f62fc73d379 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 20:52:38 +0200 Subject: [PATCH 15/40] Fix missing reference in parameters --- openfisca_core/parameters/parameter_node.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openfisca_core/parameters/parameter_node.py b/openfisca_core/parameters/parameter_node.py index e811dd6f84..8612f7992b 100644 --- a/openfisca_core/parameters/parameter_node.py +++ b/openfisca_core/parameters/parameter_node.py @@ -5,7 +5,7 @@ import typing from openfisca_core import commons, parameters, tools -from openfisca_core.parameters import config, helpers, AtInstantLike, Parameter, ParameterNodeAtInstant +from . import config, helpers, AtInstantLike, Parameter, ParameterNodeAtInstant class ParameterNode(AtInstantLike): @@ -112,7 +112,7 @@ def add_child(self, name, child): Add a new child to the node. :param name: Name of the child that must be used to access that child. Should not contain anything that could interfere with the operator `.` (dot). - :param child: The new child, an instance of :any:`Scale` or :any:`Parameter` or :any:`ParameterNode`. + :param child: The new child, an instance of :class:`ParameterScale` or :class:`Parameter` or :class:`ParameterNode`. """ if name in self.children: raise ValueError("{} has already a child named {}".format(self.name, name)) From ad9218c1523bebe8a541c74ee4eb5a09ecf5a5d1 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 21:14:46 +0200 Subject: [PATCH 16/40] Fix missing reference in variables --- openfisca_core/parameters/parameter_node.py | 2 +- openfisca_core/simulations/simulation.py | 4 ++-- openfisca_core/taxbenefitsystems/tax_benefit_system.py | 4 ++-- openfisca_core/tools/test_runner.py | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/openfisca_core/parameters/parameter_node.py b/openfisca_core/parameters/parameter_node.py index 8612f7992b..1dae81dfb4 100644 --- a/openfisca_core/parameters/parameter_node.py +++ b/openfisca_core/parameters/parameter_node.py @@ -112,7 +112,7 @@ def add_child(self, name, child): Add a new child to the node. :param name: Name of the child that must be used to access that child. Should not contain anything that could interfere with the operator `.` (dot). - :param child: The new child, an instance of :class:`ParameterScale` or :class:`Parameter` or :class:`ParameterNode`. + :param child: The new child, an instance of :class:`.ParameterScale` or :class:`.Parameter` or :class:`.ParameterNode`. """ if name in self.children: raise ValueError("{} has already a child named {}".format(self.name, name)) diff --git a/openfisca_core/simulations/simulation.py b/openfisca_core/simulations/simulation.py index b120e06fe9..5dd2694292 100644 --- a/openfisca_core/simulations/simulation.py +++ b/openfisca_core/simulations/simulation.py @@ -313,7 +313,7 @@ def get_array(self, variable_name, period): """ Return the value of ``variable_name`` for ``period``, if this value is alreay in the cache (if it has been set as an input or previously calculated). - Unlike :meth:`calculate`, this method *does not* trigger calculations and *does not* use any formula. + Unlike :meth:`.calculate`, this method *does not* trigger calculations and *does not* use any formula. """ if period is not None and not isinstance(period, Period): period = periods.period(period) @@ -321,7 +321,7 @@ def get_array(self, variable_name, period): def get_holder(self, variable_name): """ - Get the :obj:`~openfisca_core.holders.Holder` associated with the variable ``variable_name`` for the simulation + Get the :obj:`.Holder` associated with the variable ``variable_name`` for the simulation """ return self.get_variable_population(variable_name).get_holder(variable_name) diff --git a/openfisca_core/taxbenefitsystems/tax_benefit_system.py b/openfisca_core/taxbenefitsystems/tax_benefit_system.py index 4ffee5a46c..3846ee346f 100644 --- a/openfisca_core/taxbenefitsystems/tax_benefit_system.py +++ b/openfisca_core/taxbenefitsystems/tax_benefit_system.py @@ -33,7 +33,7 @@ class TaxBenefitSystem: .. attribute:: parameters - :obj:`~openfisca_core.parameters.ParameterNode` containing the legislation parameters + :obj:`.ParameterNode` containing the legislation parameters """ _base_tax_benefit_system = None _parameters_at_instant_cache = None @@ -143,7 +143,7 @@ def add_variable(self, variable): """ Adds an OpenFisca variable to the tax and benefit system. - :param Variable variable: The variable to add. Must be a subclass of Variable. + :param .Variable variable: The variable to add. Must be a subclass of Variable. :raises: :any:`VariableNameConflict` if a variable with the same name have previously been added to the tax and benefit system. """ diff --git a/openfisca_core/tools/test_runner.py b/openfisca_core/tools/test_runner.py index 30d783f169..686ad37cbc 100644 --- a/openfisca_core/tools/test_runner.py +++ b/openfisca_core/tools/test_runner.py @@ -44,7 +44,7 @@ def run_tests(tax_benefit_system, paths, options = None): If `path` is a directory, subdirectories will be recursively explored. - :param openfisca_core.taxbenefitsystems.TaxBenefitSystem tax_benefit_system: the tax-benefit system to use to run the tests + :param .TaxBenefitSystem tax_benefit_system: the tax-benefit system to use to run the tests :param (str/list) paths: A path, or a list of paths, towards the files or directories containing the tests to run. If a path is a directory, subdirectories will be recursively explored. :param dict options: See more details below. From 8037dcae02cb068bb33144c4d4d8953c56207a4b Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 21:18:10 +0200 Subject: [PATCH 17/40] Fix missing reference to error --- openfisca_core/taxbenefitsystems/tax_benefit_system.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openfisca_core/taxbenefitsystems/tax_benefit_system.py b/openfisca_core/taxbenefitsystems/tax_benefit_system.py index 3846ee346f..9817391a41 100644 --- a/openfisca_core/taxbenefitsystems/tax_benefit_system.py +++ b/openfisca_core/taxbenefitsystems/tax_benefit_system.py @@ -145,7 +145,7 @@ def add_variable(self, variable): :param .Variable variable: The variable to add. Must be a subclass of Variable. - :raises: :any:`VariableNameConflict` if a variable with the same name have previously been added to the tax and benefit system. + :raises: :exc:`.VariableNameConflictError` if a variable with the same name have previously been added to the tax and benefit system. """ return self.load_variable(variable, update = False) From 93718b8f2d80b9edb2d3ab7e0e6ac717b3d8db6e Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 21:25:09 +0200 Subject: [PATCH 18/40] Fix missing reference in tax benefit systems --- openfisca_core/taxbenefitsystems/tax_benefit_system.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/openfisca_core/taxbenefitsystems/tax_benefit_system.py b/openfisca_core/taxbenefitsystems/tax_benefit_system.py index 9817391a41..26e37a7b81 100644 --- a/openfisca_core/taxbenefitsystems/tax_benefit_system.py +++ b/openfisca_core/taxbenefitsystems/tax_benefit_system.py @@ -338,9 +338,9 @@ def get_parameters_at_instant(self, instant): """ Get the parameters of the legislation at a given instant - :param instant: string of the format 'YYYY-MM-DD' or `openfisca_core.periods.Instant` instance. + :param instant: :obj:`str` of the format 'YYYY-MM-DD' or :class:`.Instant` instance. :returns: The parameters of the legislation at a given instant. - :rtype: :any:`ParameterNodeAtInstant` + :rtype: :class:`.ParameterNodeAtInstant` """ if isinstance(instant, Period): instant = instant.start @@ -410,7 +410,7 @@ def get_variables(self, entity = None): """ Gets all variables contained in a tax and benefit system. - :param entity: If set, returns only the variable defined for the given entity. + :param .Entity entity: If set, returns only the variable defined for the given entity. :returns: A dictionnary, indexed by variable names. :rtype: dict From 37e1980ce88191ff9ed8c9223f13f00398e8b71c Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sat, 28 Aug 2021 21:27:32 +0200 Subject: [PATCH 19/40] Fix missing reference in test runner --- openfisca_core/tools/test_runner.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openfisca_core/tools/test_runner.py b/openfisca_core/tools/test_runner.py index 686ad37cbc..53d5217249 100644 --- a/openfisca_core/tools/test_runner.py +++ b/openfisca_core/tools/test_runner.py @@ -45,10 +45,10 @@ def run_tests(tax_benefit_system, paths, options = None): If `path` is a directory, subdirectories will be recursively explored. :param .TaxBenefitSystem tax_benefit_system: the tax-benefit system to use to run the tests - :param (str/list) paths: A path, or a list of paths, towards the files or directories containing the tests to run. If a path is a directory, subdirectories will be recursively explored. + :param str or list paths: A path, or a list of paths, towards the files or directories containing the tests to run. If a path is a directory, subdirectories will be recursively explored. :param dict options: See more details below. - :raises AssertionError: if a test does not pass + :raises :exc:`AssertionError`: if a test does not pass :return: the number of sucessful tests excecuted From 2f59d9c7f44b1e07387b9e0dedc7b5bb0a4533e0 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 00:02:06 +0200 Subject: [PATCH 20/40] Fix missing reference in variables --- openfisca_core/variables/__init__.py | 1 + openfisca_core/variables/typing.py | 16 ++++++++++++++++ openfisca_core/variables/variable.py | 6 ++++-- 3 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 openfisca_core/variables/typing.py diff --git a/openfisca_core/variables/__init__.py b/openfisca_core/variables/__init__.py index 3decaf8f42..fb36963f7d 100644 --- a/openfisca_core/variables/__init__.py +++ b/openfisca_core/variables/__init__.py @@ -24,3 +24,4 @@ from .config import VALUE_TYPES, FORMULA_NAME_PREFIX # noqa: F401 from .helpers import get_annualized_variable, get_neutralized_variable # noqa: F401 from .variable import Variable # noqa: F401 +from .typing import Formula # noqa: F401 diff --git a/openfisca_core/variables/typing.py b/openfisca_core/variables/typing.py new file mode 100644 index 0000000000..892ec0bf9f --- /dev/null +++ b/openfisca_core/variables/typing.py @@ -0,0 +1,16 @@ +from typing import Callable, Union + +import numpy + +from openfisca_core.parameters import ParameterNodeAtInstant +from openfisca_core.periods import Instant, Period +from openfisca_core.populations import Population, GroupPopulation + +#: A collection of :obj:`.Entity` or :obj:`.GroupEntity`. +People = Union[Population, GroupPopulation] + +#: A callable to get the parameters for the given instant. +Params = Callable[[Instant], ParameterNodeAtInstant] + +#: A callable defining a calculation, or a rule, on a system. +Formula = Callable[[People, Period, Params], numpy.ndarray] diff --git a/openfisca_core/variables/variable.py b/openfisca_core/variables/variable.py index 0cc280a267..61a5d9274f 100644 --- a/openfisca_core/variables/variable.py +++ b/openfisca_core/variables/variable.py @@ -10,7 +10,8 @@ from openfisca_core.entities import Entity from openfisca_core.indexed_enums import Enum, EnumArray from openfisca_core.periods import Period -from openfisca_core.variables import config, helpers + +from . import config, helpers class Variable: @@ -308,7 +309,8 @@ def get_formula(self, period = None): If no period is given and the variable has several formula, return the oldest formula. :returns: Formula used to compute the variable - :rtype: function + :rtype: .Formula + """ if not self.formulas: From de38100fb5a32445e3984edc7d4e4b858b637ba8 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 13:19:29 +0200 Subject: [PATCH 21/40] Split test task in subtasks --- Makefile | 55 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 37 insertions(+), 18 deletions(-) diff --git a/Makefile b/Makefile index 8e25ac2e77..01987f0208 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,11 @@ -doc = sed -n "/^$1/ { x ; p ; } ; s/\#\#/[⚙]/ ; s/\./.../ ; x" ${MAKEFILE_LIST} +help = sed -n "/^$1/ { x ; p ; } ; s/\#\#/[⚙]/ ; s/\./.../ ; x" ${MAKEFILE_LIST} ## Same as `make test`. all: test ## Install project dependencies. install: - @$(call doc,$@:) + @$(call help,$@:) @pip install --upgrade pip twine wheel @pip install --editable .[dev] --upgrade --use-deprecated=legacy-resolver @@ -13,62 +13,81 @@ install: build: setup.py @## This allows us to be sure tests are run against the packaged version @## of openfisca-core, the same we put in the hands of users and reusers. - @$(call doc,$@:) + @$(call help,$@:) @python $? bdist_wheel @find dist -name "*.whl" -exec pip install --force-reinstall {}[dev] \; ## Uninstall project dependencies. uninstall: - @$(call doc,$@:) + @$(call help,$@:) @pip freeze | grep -v "^-e" | sed "s/@.*//" | xargs pip uninstall -y ## Delete builds and compiled python files. clean: \ $(shell ls -d * | grep "build\|dist") \ $(shell find . -name "*.pyc") - @$(call doc,$@:) + @$(call help,$@:) @rm -rf $? ## Compile python files to check for syntax errors. check-syntax-errors: . - @$(call doc,$@:) + @$(call help,$@:) @python -m compileall -q $? ## Run linters to check for syntax and style errors. check-style: $(shell git ls-files "*.py") - @$(call doc,$@:) + @$(call help,$@:) @flake8 $? ## Run code formatters to correct style errors. format-style: $(shell git ls-files "*.py") - @$(call doc,$@:) + @$(call help,$@:) @autopep8 $? ## Run static type checkers for type errors. check-types: openfisca_core openfisca_web_api - @$(call doc,$@:) + @$(call help,$@:) @mypy $? ## Run openfisca-core tests. test: clean check-syntax-errors check-style check-types - @$(call doc,$@:) + @$(call help,$@:) @env PYTEST_ADDOPTS="${PYTEST_ADDOPTS} --cov=openfisca_core" pytest +## Check that the current changes do not break the doc. test.doc: + @$(call help,$@:) + @${MAKE} test.doc.checkout + @${MAKE} test.doc.install + @${MAKE} test.doc.build + +## Update the local copy of the doc. +test.doc.checkout: + @$(call help,$@:) @[ ! -d doc ] \ - && git clone https://github.com/openfisca/openfisca-doc doc \ - || { cd doc ; git pull 2> /dev/null ; } + && git clone https://github.com/openfisca/openfisca-doc doc 1> /dev/null \ + || { \ + cd doc; \ + git reset --hard; \ + git fetch --all; \ + git checkout master; \ + git pull --ff-only origin master; \ + } 1> /dev/null - @[ $$(pip freeze | grep -c "Sphinx") -eq 0 ] \ - && pip install -r doc/requirements.txt --use-deprecated=legacy-resolver \ - && pip install --editable .[dev] --upgrade --use-deprecated=legacy-resolver \ - || : +## Install doc dependencies. +test.doc.install: + @$(call help,$@:) + @pip install --requirement doc/requirements.txt --use-deprecated=legacy-resolver 1> /dev/null + @pip install --editable .[dev] --upgrade 1> /dev/null - @sphinx-build -M dummy doc/source doc/build -a -n -T -W 1> /dev/null +## Dry-build the doc. +test.doc.build: + @$(call help,$@:) + @sphinx-build -M dummy doc/source doc/build -n -q -W ## Serve the openfisca Web API. api: - @$(call doc,$@:) + @$(call help,$@:) @openfisca serve \ --country-package openfisca_country_template \ --extensions openfisca_extension_template From a2003e020ad7a43d45e9d9acbb65eaf0c8265792 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 14:11:58 +0200 Subject: [PATCH 22/40] Add option to pass the branch --- Makefile | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/Makefile b/Makefile index 01987f0208..2e56a0747e 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,5 @@ help = sed -n "/^$1/ { x ; p ; } ; s/\#\#/[⚙]/ ; s/\./.../ ; x" ${MAKEFILE_LIST} +doc_branch = master ## Same as `make test`. all: test @@ -56,6 +57,15 @@ test: clean check-syntax-errors check-style check-types ## Check that the current changes do not break the doc. test.doc: + @## Usage: + @## + @## make test.doc [branch="--ARG"] + @## + @## Examples: + @## + @## make test.doc # will check "master" in openfisca-doc + @## make test.doc branch=test-doc # will check "test-doc" in openfisca-doc + @## @$(call help,$@:) @${MAKE} test.doc.checkout @${MAKE} test.doc.install @@ -64,15 +74,13 @@ test.doc: ## Update the local copy of the doc. test.doc.checkout: @$(call help,$@:) - @[ ! -d doc ] \ - && git clone https://github.com/openfisca/openfisca-doc doc 1> /dev/null \ - || { \ - cd doc; \ - git reset --hard; \ - git fetch --all; \ - git checkout master; \ - git pull --ff-only origin master; \ - } 1> /dev/null + @[ ! -d doc ] && git clone https://github.com/openfisca/openfisca-doc doc 1> /dev/null || : + @cd doc && { \ + git reset --hard; \ + git fetch --all; \ + git checkout ${branch}; \ + git pull --ff-only origin ${branch}; \ + } 1> /dev/null ## Install doc dependencies. test.doc.install: From 7f671ed57988e06a1db91872cf78d29c4eff7075 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 15:17:13 +0200 Subject: [PATCH 23/40] Handle rebased/squashed branches --- Makefile | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 2e56a0747e..ccd659530c 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ help = sed -n "/^$1/ { x ; p ; } ; s/\#\#/[⚙]/ ; s/\./.../ ; x" ${MAKEFILE_LIST} -doc_branch = master +branch = master ## Same as `make test`. all: test @@ -76,10 +76,11 @@ test.doc.checkout: @$(call help,$@:) @[ ! -d doc ] && git clone https://github.com/openfisca/openfisca-doc doc 1> /dev/null || : @cd doc && { \ - git reset --hard; \ - git fetch --all; \ - git checkout ${branch}; \ - git pull --ff-only origin ${branch}; \ + git reset --hard ; \ + git fetch --all ; \ + [ $$(git branch --show-current) != "master" ] && git checkout master || : ; \ + [ ${branch} != "master" ] && { git branch -D ${branch} ; git checkout ${branch} ; } || : ; \ + git pull --ff-only origin ${branch} ; \ } 1> /dev/null ## Install doc dependencies. From 246bd199647d897c86a7e4e3d588a9c7f5959d4a Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 15:26:13 +0200 Subject: [PATCH 24/40] Move repo to a variable --- Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index ccd659530c..01bef322fe 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,5 @@ help = sed -n "/^$1/ { x ; p ; } ; s/\#\#/[⚙]/ ; s/\./.../ ; x" ${MAKEFILE_LIST} +repo = https://github.com/openfisca/openfisca-doc branch = master ## Same as `make test`. @@ -74,7 +75,7 @@ test.doc: ## Update the local copy of the doc. test.doc.checkout: @$(call help,$@:) - @[ ! -d doc ] && git clone https://github.com/openfisca/openfisca-doc doc 1> /dev/null || : + @[ ! -d doc ] && git clone ${repo} doc 1> /dev/null || : @cd doc && { \ git reset --hard ; \ git fetch --all ; \ From fb30b7561692d3ae2cd6a8bf47e130c97ad8352e Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 16:51:31 +0200 Subject: [PATCH 25/40] Fallback to master if no such branch --- Makefile | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/Makefile b/Makefile index 01bef322fe..b28c1e27bb 100644 --- a/Makefile +++ b/Makefile @@ -60,12 +60,18 @@ test: clean check-syntax-errors check-style check-types test.doc: @## Usage: @## - @## make test.doc [branch="--ARG"] + @## make test.doc [branch=BRANCH] @## @## Examples: @## + @## # Will check "master" in openfisca-doc. @## make test.doc # will check "master" in openfisca-doc - @## make test.doc branch=test-doc # will check "test-doc" in openfisca-doc + @## + @## # Will check "test-doc" in openfisca-doc. + @## make test.doc branch=test-doc # will check "test-doc" + @## + @## # Will check "master" if "asdf1234" does not exist. + @## make test.doc branch=asdf1234 # will fallback to "master" @## @$(call help,$@:) @${MAKE} test.doc.checkout @@ -75,14 +81,25 @@ test.doc: ## Update the local copy of the doc. test.doc.checkout: @$(call help,$@:) - @[ ! -d doc ] && git clone ${repo} doc 1> /dev/null || : + @[ ! -d doc ] && git clone ${repo} doc || : @cd doc && { \ git reset --hard ; \ git fetch --all ; \ - [ $$(git branch --show-current) != "master" ] && git checkout master || : ; \ - [ ${branch} != "master" ] && { git branch -D ${branch} ; git checkout ${branch} ; } || : ; \ - git pull --ff-only origin ${branch} ; \ - } 1> /dev/null + [ $$(git branch --show-current) != master ] && git checkout master || : ; \ + [ ${branch} != "master" ] \ + && { \ + { \ + git branch -D ${branch} 2> /dev/null ; \ + git checkout ${branch} ; \ + } \ + && git pull --ff-only origin ${branch} \ + || { \ + >&2 echo "[!] The branch '${branch}' doesn't exist, checking out 'master' instead..." ; \ + git pull --ff-only origin master ; \ + } \ + } \ + || git pull --ff-only origin master ; \ + } 1> /dev/null ## Install doc dependencies. test.doc.install: From 20d0a6761a57d6eb2723c4c1724fa6ed5756e0e3 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 17:00:45 +0200 Subject: [PATCH 26/40] Checkout doc in circleci --- .circleci/config.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.circleci/config.yml b/.circleci/config.yml index d0951f2100..399e18ada8 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -17,6 +17,10 @@ jobs: python -m venv /tmp/venv/openfisca_core echo "source /tmp/venv/openfisca_core/bin/activate" >> $BASH_ENV + - run: + name: Checkout dependencies + command: make test.doc.checkout branch=$CIRCLE_BRANCH + - run: name: Install dependencies command: | From 142776010e3212c0a412444bea36ef7f339f0b81 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 17:21:06 +0200 Subject: [PATCH 27/40] Move test docs to its own job --- .circleci/config.yml | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 399e18ada8..6149b19f86 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -17,10 +17,6 @@ jobs: python -m venv /tmp/venv/openfisca_core echo "source /tmp/venv/openfisca_core/bin/activate" >> $BASH_ENV - - run: - name: Checkout dependencies - command: make test.doc.checkout branch=$CIRCLE_BRANCH - - run: name: Install dependencies command: | @@ -52,6 +48,17 @@ jobs: COUNTRY_TEMPLATE_PATH=`python -c "import openfisca_country_template; print(openfisca_country_template.CountryTaxBenefitSystem().get_package_metadata()['location'])"` openfisca test $COUNTRY_TEMPLATE_PATH/openfisca_country_template/tests/ + test_docs: + docker: + - image: python:3.7 + + steps: + - checkout + + - run: + name: Checkout docs + command: make test.doc.checkout branch=$CIRCLE_BRANCH + check_version: docker: - image: python:3.7 @@ -127,6 +134,7 @@ workflows: build_and_deploy: jobs: - run_tests + - test_docs - check_version - submit_coverage: requires: @@ -134,6 +142,7 @@ workflows: - deploy: requires: - run_tests + - test_docs - check_version filters: branches: From 6d19e2df586fe63639bff5f054eb3bb64963400d Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 17:29:40 +0200 Subject: [PATCH 28/40] Install doc in circleci --- .circleci/config.yml | 22 ++++++++++++++++++++++ Makefile | 2 +- 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 6149b19f86..a916d71e3e 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -59,6 +59,28 @@ jobs: name: Checkout docs command: make test.doc.checkout branch=$CIRCLE_BRANCH + - restore_cache: + key: v1-py3-{{ .Branch }}-{{ checksum "setup.py" }} + + - restore_cache: + key: v1-py3-docs-{{ .Branch }}-{{ checksum "doc/requirements.txt" }} + + - run: + name: Create a virtualenv + command: | + mkdir -p /tmp/venv/openfisca_doc + python -m venv /tmp/venv/openfisca_doc + echo "source /tmp/venv/openfisca_doc/bin/activate" >> $BASH_ENV + + - run: + name: Install dependencies + command: make test.doc.install + + - save_cache: + key: v1-py3-docs-{{ .Branch }}-{{ checksum "doc/requirements.txt" }} + paths: + - /tmp/venv/openfisca_doc + check_version: docker: - image: python:3.7 diff --git a/Makefile b/Makefile index b28c1e27bb..db20ea3342 100644 --- a/Makefile +++ b/Makefile @@ -104,7 +104,7 @@ test.doc.checkout: ## Install doc dependencies. test.doc.install: @$(call help,$@:) - @pip install --requirement doc/requirements.txt --use-deprecated=legacy-resolver 1> /dev/null + @pip install --requirement doc/requirements.txt 1> /dev/null @pip install --editable .[dev] --upgrade 1> /dev/null ## Dry-build the doc. From 23b1a811c43c283fef6048ab8c1c476b6d48fd52 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 17:38:48 +0200 Subject: [PATCH 29/40] Build doc in circleci --- .circleci/config.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.circleci/config.yml b/.circleci/config.yml index a916d71e3e..93a0f0885b 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -81,6 +81,11 @@ jobs: paths: - /tmp/venv/openfisca_doc + - run: + name: Run doc tests + command: make test.doc.build + + check_version: docker: - image: python:3.7 From 7313deb0f59c8ba693c684d8b176771ae6ec03cc Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 18:20:28 +0200 Subject: [PATCH 30/40] Document how to verify that the doc build --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 8823d4c6b8..da5a333ecb 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,18 @@ exec make format-style END ``` +## Documentation + +Yet however OpenFisca does not follow a common convention for docstrings, our current toolchain allows to check whether documentation builds correctly and to update it automatically with each contribution to this repository. + +In the meantime, please take a look at our [contributing guidelines](CONTRIBUTING.md) for some general tips on how to document your contributions, and at our official documentation's [repository](https://github.com/openfisca/openfisca-doc/blob/master/README.md) to in case you want to know how to build it by yourself —and improve it! + +To verify that the documentation still builds correctly, you can run: + +```sh +make test.doc +``` + ## Serving the API OpenFisca-Core provides a Web-API. It is by default served on the `5000` port. From 5cee544b94e67ec00302d964dde24f2b51c6bef4 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 18:23:32 +0200 Subject: [PATCH 31/40] Fix wrong markup in contributing --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c54c9c6516..f900030834 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,9 +65,9 @@ We strive to deliver great error messages, which means they are: ### Example -> **Terrible**: `unexpected value`. -> **Bad**: `argument must be a string, an int, or a period`. -> **Good**: `Variable {0} has already been set for all months contained in period {1}, and value {2} provided for {1} doesn't match the total ({3}).` -> **Great**: `Inconsistent input: variable {0} has already been set for all months contained in period {1}, and value {2} provided for {1} doesn't match the total ({3}). This error may also be thrown if you try to call set_input twice for the same variable and period. See more at .` +- **Terrible**: `unexpected value`. +- **Bad**: `argument must be a string, an int, or a period`. +- **Good**: `Variable {0} has already been set for all months contained in period {1}, and value {2} provided for {1} doesn't match the total ({3}).` +- **Great**: `Inconsistent input: variable {0} has already been set for all months contained in period {1}, and value {2} provided for {1} doesn't match the total ({3}). This error may also be thrown if you try to call set_input twice for the same variable and period. See more at .` [More information](https://blogs.mulesoft.com/dev/api-dev/api-best-practices-response-handling/). From 3b5e95ca51c7d0f4194c66cd3dd9fceda4932ebb Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 19:38:05 +0200 Subject: [PATCH 32/40] Add how to doc to contributing --- CONTRIBUTING.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f900030834..8ba10fd606 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,3 +71,132 @@ We strive to deliver great error messages, which means they are: - **Great**: `Inconsistent input: variable {0} has already been set for all months contained in period {1}, and value {2} provided for {1} doesn't match the total ({3}). This error may also be thrown if you try to call set_input twice for the same variable and period. See more at .` [More information](https://blogs.mulesoft.com/dev/api-dev/api-best-practices-response-handling/). + +## Documentation + +OpenFisca does not yet follow a common convention for docstrings, so you'll find [ReStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html), [Google](http://google.github.io/styleguide/pyguide.html#Comments), and [NumPy](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) style docstrings. + +Whatever the style you choose, contributors and reusers alike will be more than thankful for the effort you put in documenting your contributions. Here are some general good practices you can follow: + +1. TL;DR: Document your intent :smiley: + +2. When adding a new module with several classes and functions, please structure it in different files, create an `__init__.py` file and document it as follows: + +```py +"""Short summary of your module. + +A longer description of what are your module's motivation, domain, and use +cases. For example, if you decide to create a caching system for OpenFisca, +consisting on different caching mechanisms, you could say that large operations +are expensive for some users, that different caching mechanisms exist, and that +this module implements some of them. + +You can then give examples on how to use your module: + + .. code-block:: python + + this = cache(result) + that = this.flush() + +Better you can write `doctests` that will be run with the test suite: + + >>> from . import Cache + >>> cache = Cache("VFS") + >>> cache.add("ratio", .45) + >>> cache.get("ratio") + .45 + +""" + +from .cache import Cache +from .strategies import Memory, Disk + +__all__ = ["Cache", "Memory", "Disk"] +``` + +3. When adding a new class, you can either document the class itself, the `__init__` method, or both: + +```py +class Cache: + """Implements a new caching system. + + Same as before, you could say this is good because virtuals systems are + great but the need a wrapper to make them work with OpenFisca. + + Document the class attributes —different from the initialisation arguments: + type (str): Type of cache. + path (str): An so on… + + Document the class arguments, here or in the `__init__` method: + type: For example if you need a ``type`` to create the :class:`.Cache`. + + Please note that if you're using Python type annotations, you don't need to + specify types in the documentation, they will be parsed and verified + automatically. + + """ + + def __init__(self, type: str) -> None: + pass + +``` + +4. Finally, when adding methods to your class, or helper functions to your module, it is very important to document their contracts: + +```py +def get(self, key: str) -> Any: + """Again, summary description. + + The long description is optional, as long as the code is easy to + understand. However, there are four key elements to help others understand + what the code does: + + * What it takes as arguments + * What it returns + * What happens if things fail + * Valid examples that can be run! + + For example if we were following the Google style, it would look like this: + + Args: + key: The ``key`` to retrieve from the :obj:`.Cache`. + + Returns: + Whatever we stored, if we stored it (see, no need to specify the type) + + Raises: + :exc:`KeyNotFoundError`: When the ``key`` wasn't found. + + Examples: + >>> cache = Cache() + >>> cache.set("key", "value") + >>> cache.get("key") + "value" + + Note: + Your examples should be simple and illustrative. For more complex + scenarios write a regular test. + + Todo: + * Accept :obj:`int` as ``key``. + * Return None when key is not found. + + .. versionadded:: 1.2.3 + This will help people to undestand the code evolution. + + .. deprecated:: 2.3.4 + This, to have time to adapt their own codebases before the code is + removed forever. + + .. seealso:: + Finally, you can help users by referencing useful documentation of + other code, like :mod:`numpy.linalg`, or even links, like the official + OpenFisca `documentation`_. + + .. _documentation: https://openfisca.org/doc/ + + """ + + pass + +``` From 7073cacfafe2c6e66187d117a683d5c49cec8561 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Sun, 29 Aug 2021 20:06:10 +0200 Subject: [PATCH 33/40] Add how to fix the doc --- README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index da5a333ecb..121f303494 100644 --- a/README.md +++ b/README.md @@ -102,12 +102,70 @@ Yet however OpenFisca does not follow a common convention for docstrings, our cu In the meantime, please take a look at our [contributing guidelines](CONTRIBUTING.md) for some general tips on how to document your contributions, and at our official documentation's [repository](https://github.com/openfisca/openfisca-doc/blob/master/README.md) to in case you want to know how to build it by yourself —and improve it! -To verify that the documentation still builds correctly, you can run: +### To verify that the documentation still builds correctly + +You can run: ```sh make test.doc ``` +### If it doesn't, or if the doc is already broken. + +Here's how you can fix it: + +1. Clone the documentation, if not yet done: + +``` +make test.doc.checkout +``` + +2. Install the documentation's dependencies, if not yet done: + +``` +make test.doc.install +``` + +3. Create a branch, both in core and in the doc, to correct the problems: + +``` +git checkout -b fix-doc +sh -c "cd doc && git checkout -b `git branch --show-current`" +``` + +4. Fix the offending problems —they could be in core, in the doc, or in both. + +You can test-drive your fixes by checking that each change works as expected: + +``` +make test.doc.build branch=`git branch --show-current` +``` + +5. Commit at each step, so you don't accidentally lose your progress: + +``` +git add -A && git commit -m "Fixed bad ref to numpy.array" +sh -c "cd doc && git add -A && git commit -m \"Fixed bad ref to numpy.array\"" +``` + +6. Once you're done, push your changes and cleanup: + +``` +git push origin `git branch --show-current` +sh -c "cd doc && git push origin `git branch --show-current`" +rm -rf doc +``` + +7. Finally, open a pull request both in [core](https://github.com/openfisca/openfisca-core/compare/master...fix-doc) and in the [doc](https://github.com/openfisca/openfisca-doc/compare/master...fix-doc). + +[CircleCI](.circleci/config.yml) will automatically try to build the documentation from the same branch in both core and the doc (in our example "fix-doc") so we can integrate first our changes to core, and then our changes to the doc. + +If no changes were needed to the doc, then your changes to core will be verified against the production version of the doc. + +If your changes concern only the doc, please take a look at the doc's [README](https://github.com/openfisca/openfisca-doc/blob/master/README.md). + +That's it! 🙌 + ## Serving the API OpenFisca-Core provides a Web-API. It is by default served on the `5000` port. From bf88c8d8aae922e18c8ea804e9e6c4eba1310ea4 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 1 Sep 2021 17:16:50 +0200 Subject: [PATCH 34/40] Fix doc tracers --- openfisca_core/tracers/__init__.py | 4 +-- openfisca_core/tracers/computation_log.py | 11 +++--- openfisca_core/tracers/flat_trace.py | 11 +++--- openfisca_core/tracers/full_tracer.py | 36 ++++++++----------- openfisca_core/tracers/performance_log.py | 16 ++++----- .../tracing_parameter_node_at_instant.py | 28 +++++++-------- 6 files changed, 46 insertions(+), 60 deletions(-) diff --git a/openfisca_core/tracers/__init__.py b/openfisca_core/tracers/__init__.py index 52f4d618ea..de489ad6d9 100644 --- a/openfisca_core/tracers/__init__.py +++ b/openfisca_core/tracers/__init__.py @@ -23,8 +23,8 @@ from .computation_log import ComputationLog # noqa: F401 from .flat_trace import FlatTrace # noqa: F401 +from .full_tracer import FullTracer # noqa: F401 +from .performance_log import PerformanceLog # noqa: F401 from .simple_tracer import SimpleTracer # noqa: F401 from .trace_node import TraceNode # noqa: F401 -from .performance_log import PerformanceLog # noqa: F401 -from .full_tracer import FullTracer # noqa: F401 from .tracing_parameter_node_at_instant import TracingParameterNodeAtInstant # noqa: F401 diff --git a/openfisca_core/tracers/computation_log.py b/openfisca_core/tracers/computation_log.py index d07b9654c4..c785fd9395 100644 --- a/openfisca_core/tracers/computation_log.py +++ b/openfisca_core/tracers/computation_log.py @@ -5,21 +5,20 @@ import numpy +from .. import tracers from openfisca_core.indexed_enums import EnumArray if typing.TYPE_CHECKING: from numpy.typing import ArrayLike - from openfisca_core.tracers import FullTracer, TraceNode - Array = Union[EnumArray, ArrayLike] class ComputationLog: - _full_tracer: FullTracer + _full_tracer: tracers.FullTracer - def __init__(self, full_tracer: FullTracer) -> None: + def __init__(self, full_tracer: tracers.FullTracer) -> None: self._full_tracer = full_tracer def display( @@ -33,12 +32,12 @@ def display( def _get_node_log( self, - node: TraceNode, + node: tracers.TraceNode, depth: int, aggregate: bool, ) -> List[str]: - def print_line(depth: int, node: TraceNode) -> str: + def print_line(depth: int, node: tracers.TraceNode) -> str: indent = ' ' * depth value = node.value diff --git a/openfisca_core/tracers/flat_trace.py b/openfisca_core/tracers/flat_trace.py index eb8e645472..d51dd2576b 100644 --- a/openfisca_core/tracers/flat_trace.py +++ b/openfisca_core/tracers/flat_trace.py @@ -5,25 +5,24 @@ import numpy +from openfisca_core import tracers from openfisca_core.indexed_enums import EnumArray if typing.TYPE_CHECKING: from numpy.typing import ArrayLike - from openfisca_core.tracers import TraceNode, FullTracer - Array = Union[EnumArray, ArrayLike] Trace = Dict[str, dict] class FlatTrace: - _full_tracer: FullTracer + _full_tracer: tracers.FullTracer - def __init__(self, full_tracer: FullTracer) -> None: + def __init__(self, full_tracer: tracers.FullTracer) -> None: self._full_tracer = full_tracer - def key(self, node: TraceNode) -> str: + def key(self, node: tracers.TraceNode) -> str: name = node.name period = node.period return f"{name}<{period}>" @@ -71,7 +70,7 @@ def serialize( def _get_flat_trace( self, - node: TraceNode, + node: tracers.TraceNode, ) -> Trace: key = self.key(node) diff --git a/openfisca_core/tracers/full_tracer.py b/openfisca_core/tracers/full_tracer.py index b7755683f8..3fa46de5ab 100644 --- a/openfisca_core/tracers/full_tracer.py +++ b/openfisca_core/tracers/full_tracer.py @@ -4,13 +4,7 @@ import typing from typing import Dict, Iterator, List, Optional, Union -from openfisca_core.tracers import ( - ComputationLog, - FlatTrace, - PerformanceLog, - SimpleTracer, - TraceNode, - ) +from .. import tracers if typing.TYPE_CHECKING: from numpy.typing import ArrayLike @@ -22,12 +16,12 @@ class FullTracer: - _simple_tracer: SimpleTracer + _simple_tracer: tracers.SimpleTracer _trees: list - _current_node: Optional[TraceNode] + _current_node: Optional[tracers.TraceNode] def __init__(self) -> None: - self._simple_tracer = SimpleTracer() + self._simple_tracer = tracers.SimpleTracer() self._trees = [] self._current_node = None @@ -45,7 +39,7 @@ def _enter_calculation( variable: str, period: Period, ) -> None: - new_node = TraceNode( + new_node = tracers.TraceNode( name = variable, period = period, parent = self._current_node, @@ -68,7 +62,7 @@ def record_parameter_access( if self._current_node is not None: self._current_node.parameters.append( - TraceNode(name = parameter, period = period, value = value), + tracers.TraceNode(name = parameter, period = period, value = value), ) def _record_start_time( @@ -109,20 +103,20 @@ def stack(self) -> Stack: return self._simple_tracer.stack @property - def trees(self) -> List[TraceNode]: + def trees(self) -> List[tracers.TraceNode]: return self._trees @property - def computation_log(self) -> ComputationLog: - return ComputationLog(self) + def computation_log(self) -> tracers.ComputationLog: + return tracers.ComputationLog(self) @property - def performance_log(self) -> PerformanceLog: - return PerformanceLog(self) + def performance_log(self) -> tracers.PerformanceLog: + return tracers.PerformanceLog(self) @property - def flat_trace(self) -> FlatTrace: - return FlatTrace(self) + def flat_trace(self) -> tracers.FlatTrace: + return tracers.FlatTrace(self) def _get_time_in_sec(self) -> float: return time.time_ns() / (10**9) @@ -136,7 +130,7 @@ def generate_performance_graph(self, dir_path: str) -> None: def generate_performance_tables(self, dir_path: str) -> None: self.performance_log.generate_performance_tables(dir_path) - def _get_nb_requests(self, tree: TraceNode, variable: str) -> int: + def _get_nb_requests(self, tree: tracers.TraceNode, variable: str) -> int: tree_call = tree.name == variable children_calls = sum( self._get_nb_requests(child, variable) @@ -159,7 +153,7 @@ def get_flat_trace(self) -> dict: def get_serialized_flat_trace(self) -> dict: return self.flat_trace.get_serialized_trace() - def browse_trace(self) -> Iterator[TraceNode]: + def browse_trace(self) -> Iterator[tracers.TraceNode]: def _browse_node(node): yield node diff --git a/openfisca_core/tracers/performance_log.py b/openfisca_core/tracers/performance_log.py index cdd66a286b..754d7f8056 100644 --- a/openfisca_core/tracers/performance_log.py +++ b/openfisca_core/tracers/performance_log.py @@ -7,11 +7,9 @@ import os import typing -from openfisca_core.tracers import TraceNode +from .. import tracers if typing.TYPE_CHECKING: - from openfisca_core.tracers import FullTracer - Trace = typing.Dict[str, dict] Calculation = typing.Tuple[str, dict] SortedTrace = typing.List[Calculation] @@ -19,7 +17,7 @@ class PerformanceLog: - def __init__(self, full_tracer: FullTracer) -> None: + def __init__(self, full_tracer: tracers.FullTracer) -> None: self._full_tracer = full_tracer def generate_graph(self, dir_path: str) -> None: @@ -87,10 +85,10 @@ def _aggregate_calculations(calculations: list) -> dict: return { 'calculation_count': calculation_count, - 'calculation_time': TraceNode.round(calculation_time), - 'formula_time': TraceNode.round(formula_time), - 'avg_calculation_time': TraceNode.round(calculation_time / calculation_count), - 'avg_formula_time': TraceNode.round(formula_time / calculation_count), + 'calculation_time': tracers.TraceNode.round(calculation_time), + 'formula_time': tracers.TraceNode.round(formula_time), + 'avg_calculation_time': tracers.TraceNode.round(calculation_time / calculation_count), + 'avg_formula_time': tracers.TraceNode.round(formula_time / calculation_count), } def _groupby(calculation: Calculation) -> str: @@ -114,7 +112,7 @@ def _json(self) -> dict: 'children': children, } - def _json_tree(self, tree: TraceNode) -> dict: + def _json_tree(self, tree: tracers.TraceNode) -> dict: calculation_total_time = tree.calculation_time() children = [self._json_tree(child) for child in tree.children] diff --git a/openfisca_core/tracers/tracing_parameter_node_at_instant.py b/openfisca_core/tracers/tracing_parameter_node_at_instant.py index 9775192740..89d9b8fb01 100644 --- a/openfisca_core/tracers/tracing_parameter_node_at_instant.py +++ b/openfisca_core/tracers/tracing_parameter_node_at_instant.py @@ -5,21 +5,17 @@ import numpy -from openfisca_core.parameters import ( - config, - ParameterNodeAtInstant, - VectorialParameterNodeAtInstant, - ) +from openfisca_core import parameters -if typing.TYPE_CHECKING: - from numpy.typing import ArrayLike +from .. import tracers - from openfisca_core.tracers import FullTracer +ParameterNode = Union[ + parameters.VectorialParameterNodeAtInstant, + parameters.ParameterNodeAtInstant, + ] - ParameterNode = Union[ - VectorialParameterNodeAtInstant, - ParameterNodeAtInstant, - ] +if typing.TYPE_CHECKING: + from numpy.typing import ArrayLike Child = Union[ParameterNode, ArrayLike] @@ -29,7 +25,7 @@ class TracingParameterNodeAtInstant: def __init__( self, parameter_node_at_instant: ParameterNode, - tracer: FullTracer, + tracer: tracers.FullTracer, ) -> None: self.parameter_node_at_instant = parameter_node_at_instant self.tracer = tracer @@ -57,14 +53,14 @@ def get_traced_child( if isinstance( child, - (ParameterNodeAtInstant, VectorialParameterNodeAtInstant), + (parameters.ParameterNodeAtInstant, parameters.VectorialParameterNodeAtInstant), ): return TracingParameterNodeAtInstant(child, self.tracer) if not isinstance(key, str) or \ isinstance( self.parameter_node_at_instant, - VectorialParameterNodeAtInstant, + parameters.VectorialParameterNodeAtInstant, ): # In case of vectorization, we keep the parent node name as, for # instance, rate[status].zone1 is best described as the value of @@ -74,7 +70,7 @@ def get_traced_child( else: name = '.'.join([self.parameter_node_at_instant._name, key]) - if isinstance(child, (numpy.ndarray,) + config.ALLOWED_PARAM_TYPES): + if isinstance(child, (numpy.ndarray,) + parameters.ALLOWED_PARAM_TYPES): self.tracer.record_parameter_access(name, period, child) return child From 7b0d865e09b3ef92ed9e4dfaa73694b5041361bb Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 1 Sep 2021 17:37:45 +0200 Subject: [PATCH 35/40] Fix doc parameters --- openfisca_core/parameters/helpers.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openfisca_core/parameters/helpers.py b/openfisca_core/parameters/helpers.py index 0d0698ca36..75d5a18b73 100644 --- a/openfisca_core/parameters/helpers.py +++ b/openfisca_core/parameters/helpers.py @@ -19,7 +19,7 @@ def load_parameter_file(file_path, name = ''): """ Load parameters from a YAML file (or a directory containing YAML files). - :returns: An instance of :any:`ParameterNode` or :any:`Scale` or :any:`Parameter`. + :returns: An instance of :class:`.ParameterNode` or :class:`.ParameterScale` or :class:`.Parameter`. """ if not os.path.exists(file_path): raise ValueError("{} does not exist".format(file_path)) From bdda1a99a03377681aa006e294352e874d59e785 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 1 Sep 2021 17:52:05 +0200 Subject: [PATCH 36/40] Fix doc variables --- openfisca_core/variables/helpers.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/openfisca_core/variables/helpers.py b/openfisca_core/variables/helpers.py index 8dec55d0f8..335a585498 100644 --- a/openfisca_core/variables/helpers.py +++ b/openfisca_core/variables/helpers.py @@ -1,14 +1,14 @@ from __future__ import annotations -import typing import sortedcontainers +from typing import Optional -if typing.TYPE_CHECKING: - from openfisca_core.periods import Period - from openfisca_core.variables import Variable +from openfisca_core.periods import Period +from .. import variables -def get_annualized_variable(variable: Variable, annualization_period: typing.Optional[Period] = None) -> Variable: + +def get_annualized_variable(variable: variables.Variable, annualization_period: Optional[Period] = None) -> variables.Variable: """ Returns a clone of ``variable`` that is annualized for the period ``annualization_period``. When annualized, a variable's formula is only called for a January calculation, and the results for other months are assumed to be identical. From 01f31936bf24e120a920ad70fae3e61879f8d6c8 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Thu, 2 Sep 2021 00:55:45 +0200 Subject: [PATCH 37/40] Fix default branch to current --- Makefile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index db20ea3342..1a273e2ed7 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ help = sed -n "/^$1/ { x ; p ; } ; s/\#\#/[⚙]/ ; s/\./.../ ; x" ${MAKEFILE_LIST} repo = https://github.com/openfisca/openfisca-doc -branch = master +branch = $(shell git branch --show-current) ## Same as `make test`. all: test @@ -64,14 +64,14 @@ test.doc: @## @## Examples: @## - @## # Will check "master" in openfisca-doc. - @## make test.doc # will check "master" in openfisca-doc + @## # Will check the current branch in openfisca-doc. + @## make test.doc @## @## # Will check "test-doc" in openfisca-doc. - @## make test.doc branch=test-doc # will check "test-doc" + @## make test.doc branch=test-doc @## @## # Will check "master" if "asdf1234" does not exist. - @## make test.doc branch=asdf1234 # will fallback to "master" + @## make test.doc branch=asdf1234 @## @$(call help,$@:) @${MAKE} test.doc.checkout From d991bdcdc160ca829628a75a8c741e8527c4fbb1 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Tue, 7 Sep 2021 19:52:45 +0200 Subject: [PATCH 38/40] Change commit message in README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 121f303494..36bc2357b1 100644 --- a/README.md +++ b/README.md @@ -144,8 +144,8 @@ make test.doc.build branch=`git branch --show-current` 5. Commit at each step, so you don't accidentally lose your progress: ``` -git add -A && git commit -m "Fixed bad ref to numpy.array" -sh -c "cd doc && git add -A && git commit -m \"Fixed bad ref to numpy.array\"" +git add -A && git commit -m "Fix outdated argument for Entity" +sh -c "cd doc && git add -A && git commit -m \"Fix outdated argument for Entity\"" ``` 6. Once you're done, push your changes and cleanup: From 95e94a5d1dedf0d5e54c3e10ba6b44bee7837c81 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Tue, 7 Sep 2021 20:04:06 +0200 Subject: [PATCH 39/40] Use hyphens in Makefile --- .circleci/config.yml | 6 +++--- Makefile | 22 +++++++++++----------- README.md | 8 ++++---- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 93a0f0885b..c9f90c832b 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -57,7 +57,7 @@ jobs: - run: name: Checkout docs - command: make test.doc.checkout branch=$CIRCLE_BRANCH + command: make test-doc-checkout branch=$CIRCLE_BRANCH - restore_cache: key: v1-py3-{{ .Branch }}-{{ checksum "setup.py" }} @@ -74,7 +74,7 @@ jobs: - run: name: Install dependencies - command: make test.doc.install + command: make test-doc-install - save_cache: key: v1-py3-docs-{{ .Branch }}-{{ checksum "doc/requirements.txt" }} @@ -83,7 +83,7 @@ jobs: - run: name: Run doc tests - command: make test.doc.build + command: make test-doc-build check_version: diff --git a/Makefile b/Makefile index 1a273e2ed7..c139b6aac0 100644 --- a/Makefile +++ b/Makefile @@ -57,29 +57,29 @@ test: clean check-syntax-errors check-style check-types @env PYTEST_ADDOPTS="${PYTEST_ADDOPTS} --cov=openfisca_core" pytest ## Check that the current changes do not break the doc. -test.doc: +test-doc: @## Usage: @## - @## make test.doc [branch=BRANCH] + @## make test-doc [branch=BRANCH] @## @## Examples: @## @## # Will check the current branch in openfisca-doc. - @## make test.doc + @## make test-doc @## @## # Will check "test-doc" in openfisca-doc. - @## make test.doc branch=test-doc + @## make test-doc branch=test-doc @## @## # Will check "master" if "asdf1234" does not exist. - @## make test.doc branch=asdf1234 + @## make test-doc branch=asdf1234 @## @$(call help,$@:) - @${MAKE} test.doc.checkout - @${MAKE} test.doc.install - @${MAKE} test.doc.build + @${MAKE} test-doc-checkout + @${MAKE} test-doc-install + @${MAKE} test-doc-build ## Update the local copy of the doc. -test.doc.checkout: +test-doc-checkout: @$(call help,$@:) @[ ! -d doc ] && git clone ${repo} doc || : @cd doc && { \ @@ -102,13 +102,13 @@ test.doc.checkout: } 1> /dev/null ## Install doc dependencies. -test.doc.install: +test-doc-install: @$(call help,$@:) @pip install --requirement doc/requirements.txt 1> /dev/null @pip install --editable .[dev] --upgrade 1> /dev/null ## Dry-build the doc. -test.doc.build: +test-doc-build: @$(call help,$@:) @sphinx-build -M dummy doc/source doc/build -n -q -W diff --git a/README.md b/README.md index 36bc2357b1..7f253c9114 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ In the meantime, please take a look at our [contributing guidelines](CONTRIBUTIN You can run: ```sh -make test.doc +make test-doc ``` ### If it doesn't, or if the doc is already broken. @@ -117,13 +117,13 @@ Here's how you can fix it: 1. Clone the documentation, if not yet done: ``` -make test.doc.checkout +make test-doc-checkout ``` 2. Install the documentation's dependencies, if not yet done: ``` -make test.doc.install +make test-doc-install ``` 3. Create a branch, both in core and in the doc, to correct the problems: @@ -138,7 +138,7 @@ sh -c "cd doc && git checkout -b `git branch --show-current`" You can test-drive your fixes by checking that each change works as expected: ``` -make test.doc.build branch=`git branch --show-current` +make test-doc-build branch=`git branch --show-current` ``` 5. Commit at each step, so you don't accidentally lose your progress: From df51e0b5b799149c82faaec3cbfefe8952429653 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 1 Sep 2021 18:03:48 +0200 Subject: [PATCH 40/40] Bump minor to 35.5.0 --- CHANGELOG.md | 23 +++++++++++++++++++++++ setup.py | 2 +- 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a895e9db65..7bed8ae1d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,28 @@ # Changelog +## 35.5.0 [#1038](https://github.com/openfisca/openfisca-core/pull/1038) + +#### New Features + +- Introduce `openfisca_core.variables.typing` + - Documents the signature of formulas + - Note: as formulas are generated dynamically, documenting them is tricky + +#### Bug Fixes + +- Fix the official doc + - Corrects malformed docstrings + - Fix missing and/ou outdated references + +#### Technical Changes + +- Add tasks to automatically validate that changes do not break the documentation + +#### Documentation + +- Add steps to follow in case the documentation is broken +- Add general documenting guidelines in CONTRIBUTING.md + ### 35.4.2 [#1026](https://github.com/openfisca/openfisca-core/pull/1026) #### Bug fix diff --git a/setup.py b/setup.py index d67113a6fd..88e2772a2c 100644 --- a/setup.py +++ b/setup.py @@ -36,7 +36,7 @@ setup( name = 'OpenFisca-Core', - version = '35.4.2', + version = '35.5.0', author = 'OpenFisca Team', author_email = 'contact@openfisca.org', classifiers = [