OpenFisca Doc

OpenFisca is versatile and free micro-simulation software. This repository contains the source code of its online documentation.

Installation

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/activate

To install dependencies, run:

make install

Build

To build the HTML documentation, run:

make html

The HTML output will be generated in the build/html directory.

Dev

To serve the documentation in dev mode, run:

make dev

The documentation will be served on http://127.0.0.1:8000

Test

To test the documentation, run:

make test

This will also lint the source files using Markdownlint, for which you will need Node and NPM.

Autoformat

If make lint gives you errors, you can try running the following command to automatically format your contributions according to the existing conventions:

make format

Fixing the doc

If 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 install

Create a branch to correct the problems:

git checkout -b fix-doc

Fix the offending problems. You can test-drive your fixes by checking that each change works as expected:

make test

Commit 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! 🙌

Using icons

You can use icons by choosing one from Lucide and adapting the code <i icon-name="$ICON_NAME"></i> with the relevant icon name.

Deploy

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.