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.