Fix documentation - Githubissues

openfisca / openfisca-core

OpenFisca core engine. See other repositories for countries-specific code & data.

https://openfisca.org

GNU Affero General Public License v3.0

168 stars 75 forks source link

Fix documentation #1038

Closed bonjourmauko closed 3 years ago

bonjourmauko commented 3 years ago

Partially fixes openfisca/openfisca-doc#244 Depended upon by #1033 #1021

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

benjello commented 3 years ago

@maukoquiroga got this error when running make doc.test:

Warning, treated as error:
/home/mbenjelloul/openfisca/openfisca-core/openfisca_core/indexed_enums/enum.py:docstring of openfisca_core.indexed_enums.Enum.encode:None: WARNING: py:obj reference target not found: numpy.ndarray

benjello commented 3 years ago

@maukoquiroga : I got the same error as above even after the 3 last commits.

bonjourmauko commented 3 years ago

Hi @benjello ! As I put in the README.md, you have to run:

make test.doc branch=`git branch --show-current`

So it compares these changes with the corresponding ones in the doc repo.

Please let me know if that works for you, and if and how could I render the documentation clearer.

(Maybe making it the default behaviour? I didn't as per the least surprise principle, but it may in fact be more intuitive).

bonjourmauko commented 3 years ago

By the way @MattiSG I did actually struggle to get this automated with make, and I have been practicing stoicism so I am in no (hard) way emotionally attached to keep this overly complex and fragile task, quite the contrary, I just hope it won't be a blocking factor for this specific changeset 😃

benjello commented 3 years ago

Thanks @maukoquiroga ! I tested make test-doc and it worked well. I didn't test the occurrence of an error and how to fix it, but I am all in afvor of merging this PR and improving it if needed later when use case emerge.

benjello commented 3 years ago

@HAEKADI, I assume that you are almost aligned with me ;-) (or do not have a strong opinion which is equivalent) Review from @MattiSG and @sandcha might be useful as well ! ()