OpenFisca is versatile and free micro-simulation software. This repository contains the source code of its online documentation.
This documentation is built with Sphinx, a Python documentation generator. You will thus need to install a Python runtime to build it. The version to install is specified in the runtime.txt file.
In order to avoid conflicting dependencies with other projects on your local machine, it is recommended to install its dependencies in a virtual environment. To create a virtual environment, run:
python3 -m venv .venv
source .venv/bin/activateTo install dependencies, run:
make installTo build the HTML documentation, run:
make htmlThe HTML output will be generated in the build/html directory.
To serve the documentation in dev mode, run:
make devThe documentation will be served on http://127.0.0.1:8000
To test the documentation, run:
make testThis will also lint the source files using Markdownlint, for which you will need Node and NPM.
If make lint gives you errors, you can try running the following command to automatically format your contributions according to the existing conventions:
make formatIf the tests fail, here's what you can do:
If the errors also concern OpenFisca-Core, please take a look at the README.
If not, clone & install the documentation:
git clone https://github.com/openfisca/openfisca-doc
make installCreate a branch to correct the problems:
git checkout -b fix-docFix the offending problems. You can test-drive your fixes by checking that each change works as expected:
make testCommit at each step, so you don't accidentally lose your progress:
git add -A && git commit -m "Fixed missing doctree"Once you're done, push your changes:
git push origin `git branch --show-current`Finally, open a pull request.
That's it! 🙌
You can use icons by choosing one from Lucide and adapting the code <i icon-name="$ICON_NAME"></i> with the relevant icon name.
The documentation is built as a static website on GitHub Actions with Sphinx. The built files are committed and pushed to the doc folder of the GitHub Pages-published branch of the openfisca.org repository.
OpenFisca-Core triggers a deployment on the Doc repository whenever a new Core version is deployed, to ensure that the Python and Web API auto-generated documentations are up to date. This is done with workflow_dispatch using a personal access token of @openfisca-bot. This personal access token has a maximum lifetime of one year, and will thus need to be updated every year.