Creating documentation

For writing guides and manuals, we are using Sphinx which is a Python package.

Click here for tips on getting started with Sphinx

Doxygen will be used for automatically generating documentation describing our code, such as inheritance diagrams, man pages and call trees.

We have created a GitHub repository for holding documentation called :code:JCSDA/jedi-docs. Please place your documentation in this repository and place the appropriate links and text to your documentation in the top level index.html file.

To add your documentation to the jedi-docs repository you need to follow the Git flow paradigm.

First let’s make sure you have the latest version of the code. To pull the latest version of the develop branch run:

git checkout develop  # checkout develop branch
git pull              # get the latest develop branch

create a new feature branch in the jedi-docs repository and check it out by running:

git checkout -b feature/my-branch

You can check which branch you are currently on by running:

git branch

After creating and checking out your feature branch you can edit (or add new) files in the jedi-docs repository. To edit the current documentations you can edit .rst files. If you want to add a new section to the documentation you need to create a new .rst file and also register the new file in index.rst in your working directory.

You can push your changes back to the repository using git add, git commit, and git push commands as described here.

Note

If you use git flow, you may need to initialize git flow for the repository by running git flow init -d