Python - Documentation

From XennisWiki
(Redirected from Sphinx)
Jump to: navigation, search

Documentation tools written in Python.

MkDocs

Install and run

Install Pip module: mkdocs

Optional create automatically a project

mkdocs new my-project
cd my-project

Run MkDocs to see the documentation at http://localhost:8000

mkdocs serve

Configuration

Example mkdocs.yml configuration

site_name: Example Project
repo_url: https://github.com/example/example_project
repo_name: GitHub
theme: readthedocs
site_description: Documentation for Example Project
include_search: true
pages:
- ['index.md', 'Home']
- ['deployment.md', 'Developer manuel', 'Deployment']
- ['api.md', 'User manuel', 'API']

The configuration includes the files docs/index.md, docs/deployment.md and docs/api.md. Create these files and write the documentation in Markdown. You maybe use <h1>Title</h1> for the main title of a file so that it does not appear in the navigation.

Sphinx

Install and setup

Install Pip module: sphinx

Follow the instruction of the quickstart

cd my-project
mkdir docs
sphinx-quickstart

Configuration

Create the files in the format you selected during the setup. Run make html to create the html files of the documentation. You maybe use make clean to delete these files.

See also

External links