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:

Build

To build the HTML documentation, run:

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

Dev

To serve the documentation in dev mode, run:

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

Test

To test the documentation, run:

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:

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:

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

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