Skip to content

Latest commit

 

History

History
105 lines (71 loc) · 2.94 KB

.documentation.md

File metadata and controls

105 lines (71 loc) · 2.94 KB

Documentation

We use sphinx to build and readthedocs to host the documentation.

How create doc with Sphinx

1. Getting to know Sphinx

1.1 Sphinx

Sphinx is a documentation generator or a tool that translates a set of plain text source files into various output formats, automatically producing cross-references, indices, etc. That is, if you have a directory containing a bunch of reStructuredText or Markdown documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), man pages and much more.

For more information access the documentation here.

1.1.1. Sphinx APIDoc

It is a tool for automatic generation of Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API documentation tools. For more information access the documentation here.

2. Tutorial

Here we will describe how to create a docs, configure the conf.py file and update the documentation.

2.1. Create the documentation

  1. Install Sphinx!

pip install Sphinx pip install pip install sphinx_rtd_theme

  1. First, make the directory docs with command

mkdir docs

  1. Run the following command

sphinx-apidoc -o docs pymove -full

Finish! Your documentation has been created! The generated files are of the extension .rst (reStructuredText). There are two main files:

  • index.rst: is the root of your documentation

  • conf.py: where are the dependencies and internal settings, such as the html theme, and imports and the path to the library.

2.2. Configure the conf.py

In the file conf.py, include the following imports:

import os

import sys

And include the following code snippet, referring to the library path:

sys.path.append(os.path.join(os.path.dirname(__name__), '..'))

Now, you must:

  1. Describe project informations
  2. Configure extensions
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx_rtd_theme'
]
  1. Configure theme html

html_theme = 'sphinx_rtd_theme'

and finish!

2.3. Generating the .html files

To generate the .html files, just access the docs folder, just run the following command:

make doc

2.4. Hospedando docs in Readthedocs

  1. Log in to Readthedocs with your github account

  2. Import the project/repository

  3. Select the project and the branch where your project contains the documentation

  4. Click on build project

  5. After preparing the environment and finalizing the building process, you can see your project's documentation in view docs.

2.5. Update the documentation

To update the documentation just run the following command and move the generated files to the folder references/.

sphinx-apidoc -f -o docs/references pymove pymove/tests/