Getting started
Welcome to The Pencil Code documentation page! To help you get started, here are a few tips for using and contributing to this space:
Using the documentation
The purpose of this space is to bring together The Pencil Code documentation in a unified format and organized in a logical, hierarchical structure. The ultimate goal is to make the process of locating and reading documentation as easy and enjoyable as possible.
Contributing to the documentation
In order to contribute to the documentation, you will need to clone the GitHub repository containing the source of the documentation, edit the necessary files, and then push your changes back to the repository. The documentation will then be built and deployed automatically using the ReadTheDocs platform.
The following instructions are for Ubuntu systems (64-bit, 16.04+):
Cloning the repository
Go to a directory and type in a terminal:
git clone git@github.com:pencil-code/pencil-code.git
If you have a github username ‘MY_GITHUB_NAME’ and like to submit changes you can use:
git clone http://MY_GITHUB_NAME@github.com/pencil-code/pencil-code.git
git config --global credential.helper 'cache --timeout=3600'
git config --global branch.autosetuprebase always
After cloning the repository, you can access all the documentation files in the directory:
cd pencil-code/doc/readthedocs
How to build locally (fast)
Follow these instructions to build the reStructuredText documentation (i.e., manuals), but not the auto-generated code documentation. The build is very fast (few seconds).
Make sure you have
sphinxinstalled and thatsphinx-buildis in yourPATH.Make sure you have the following
python3scripts installed (e.g., withpip3):sphinx-rtd-theme sphinxcontrib-images sphinx-fortran sphinx-git
Build:
# Fast: do not build auto-generated code documentation make fast
The html files will be built into _build/html.
How to build locally (slow)
Follow these instructions to build the complete documentation, including the auto-generated code documentation. The build is slow (several minutes).
Warning
Sphinx imports the entire Pencil package in order to generate the documentation (right now, only the Pencil Python module. More to come!)
Make sure you have
sphinxinstalled and thatsphinx-buildis in yourPATH.Make sure you have the following
python3scripts installed (e.g., withpip3):sphinx-rtd-theme sphinxcontrib-images sphinx-js astropy numpy scipy
Update your local copy of the repository (in order to have freshly autogenerated documentation) and build:
git pull --rebase
Build:
# Slow: build auto-generated code documentation make html
The html files will be built into _build/html.
Tips for the Python documentation (numpy style)
The Pencil Python documentation follows the numpy style docstring convention.
For a thorough example please see the napoleon extension website.
Tip
To make sure sphinx will be successful in generating the documentation, go to the python directory
# from the directory containing conf.py
cd ../../python
python
and try to import
the pencil package. If the import succeeds, it is likely
that sphinx will also succeed.
Tips for the IDL documentation
Not yet available.
Tips for the Fortran documentation
Not yet available.
Revision history