Sphinx for a personal website/wiki [fr]

Sphinx est un outil pythonnique pour générer de la documentation dans de multiples formats, en particulier sous forme de site web. Il permet au rédacteur d’écrire toutes ses pages en reStructuredText, langage parfait pour écrire du texte depuis son éditeur préféré.

Pour créer un site web personnel, il s’avère que Sphinx s’avère tout à fait adapté :

• Des générateurs de blogs comme Pelican sont tout aussi attrayants. Toutefois, le format blog ne semble pas adapté pour un site personnel, qui se présente plutôt en format wiki (pages rangées dans leurs catégories/sous-catégories, pas par date).

• Les systèmes de wiki sont toujours de gros bouzins dynamiques, alors qu’il est tellement plus simple d’écrire ses articles depuis son éditeur de texte, et de générer des pages statiques.

Il y a toutefois quelques petites choses à modifier, par rapport à une documentation.

Mise en place

Une fois que sphinx est installé, créez votre projet avec la commande « sphinx-quickstart ».

Conf.py

Vous aurez un fichier conf.py, qu’il va falloir adapter :

# On n'active aucune extension de Sphinx
extensions = []

source_suffix = '.rst'

templates_path = ['_templates']

master_doc = 'index'

project = 'nom du site'

language = 'fr'

exclude_patterns = ['_build']

pygments_style = 'sphinx'

html_theme = 'pyramid' # pyramid et nature sont sympa :)

html_title = "titre du site"

html_static_path = ['_static']

# Pour rajouter des thèmes supplémentaires
html_theme_path = ['_themes']

#html_favicon = 'favicon.png'

# Très important pour avoir un menu plus adapté que celui par défaut...
html_sidebars = {'**': ['menu.html', 'localtoc.html']}

# Pas besoin d'un index de toutes les pages
html_use_index = False

# On n'inclue pas les sources des pages
html_copy_source = False
html_show_sourcelink = False

htmlhelp_basename = 'palkeodoc'

# On peut masquer le copyright
html_show_copyright = False

# Et aussi les permalink dans les titres
html_add_permalinks = False

Ces directives devraient être suffisantes à elles seules pour configurer tout votre Sphinx.

Navigation dans le menu

Dans le menu vertical, au dessus du sommaire de la page courante, il est possible de rajouter des liens vers les principales rubriques de votre site.

Pour cela, dans le répertoire _templates créez un fichier menu.html :

<h3><a href="{{ pathto(master_doc) }}">nom du site</a></h3>
{{ toctree() }}

Navigation dans le header

Mais il est également possible de modifier le header pour afficher des liens vers les rubriques de votre choix. Il suffit de créer un fichier layout.html dans le répertoire _templates :

{% extends "!layout.html" %}
{%- set rellinks = [] %}
{% block rootrellink %}</pre>
<ul>
    <li><a href="index.html">Home</a> |</li>
    <li><a href="resume.html">Resume</a> |</li>
    <li><a href="projects.html">Projects</a> |</li>
    <li><a href="interest.html">Interest</a> |</li>
    <li><a href="contact.html">Contact</a></li>
    <li>{% endblock %}
{% block relbar2 %}
{% endblock %}

Notez que le {%- set rellinks = [] %} permet de masquer les boutons « précédent » et « suivant » des pages.

Previous: Data compression [fr]   Next: Introduction to Python [fr]