https://github.com/openfisca/openfisca-doc
User guide of OpenFisca
https://github.com/openfisca/openfisca-doc
documentation gitbook hacktoberfest openfisca
Last synced: 5 months ago
JSON representation
User guide of OpenFisca
- Host: GitHub
- URL: https://github.com/openfisca/openfisca-doc
- Owner: openfisca
- License: agpl-3.0
- Created: 2015-09-10T14:03:10.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2026-01-11T11:10:40.000Z (5 months ago)
- Last Synced: 2026-01-11T15:55:53.958Z (5 months ago)
- Topics: documentation, gitbook, hacktoberfest, openfisca
- Language: JavaScript
- Homepage: https://openfisca.org/doc
- Size: 18.1 MB
- Stars: 19
- Watchers: 20
- Forks: 23
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenFisca Doc
[OpenFisca](http://openfisca.org/doc/) is versatile and free micro-simulation software. This repository contains the source code of its [online documentation](http://openfisca.org/doc/).
## Installation
This documentation is built with [Sphinx](https://www.sphinx-doc.org/), a Python documentation generator. You will thus need to install a [Python runtime](https://www.python.org/downloads/) 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:
```sh
python3 -m venv .venv
source .venv/bin/activate
```
To install dependencies, run:
```sh
make install
```
## Build
To build the HTML documentation, run:
```sh
make html
```
The HTML output will be generated in the `build/html` directory.
## Dev
To serve the documentation in dev mode, run:
```sh
make dev
```
The documentation will be served on `http://127.0.0.1:8000`
## Test
To test the documentation, run:
```sh
make test
```
This will also lint the source files using [Markdownlint](https://github.com/DavidAnson/markdownlint), for which you will need [Node](https://nodejs.org) 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:
```sh
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](https://github.com/openfisca/openfisca-core/blob/master/README.md).
If not, clone & install the documentation:
```sh
git clone https://github.com/openfisca/openfisca-doc
make install
```
Create a branch to correct the problems:
```sh
git checkout -b fix-doc
```
Fix the offending problems. You can test-drive your fixes by checking that each change works as expected:
```sh
make test
```
Commit at each step, so you don't accidentally lose your progress:
```sh
git add -A && git commit -m "Fixed missing doctree"
```
Once you're done, push your changes:
```sh
git push origin `git branch --show-current`
```
Finally, open a [pull request](https://github.com/openfisca/openfisca-doc/compare/main...fix-doc).
That's it! 🙌
## Using icons
You can use icons by choosing one from [Lucide](https://lucide.dev) and adapting the code `` 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`](https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#create-a-workflow-dispatch-event--fine-grained-access-tokens) 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.