sphinxSimDoc Documentation¶
¶
A collection of simple docs built from scratch using sampledocs from Sphinx and also by using Sphinx.
Introduction¶
This is a tutorial introduction to quickly get you up and running with your own sphinx documentation system. We’ll cover installing sphinx, customizing the look and feel and a little bit more general stuffs.
If you follow along the tutrial, you’ll start with nothing and end up with this – documentation site itself, thus the method 2 mentioned in the README, and hence the recursive nature.
It’s the bootstrapping documenation tutorial that writes itself. Voila!
Documentation¶
This documentation is also available in PDF format.
User’s guide¶
Details¶
Below are the details of author and license of the this package.
Software¶
| Author: | Anirban Roy Das |
|---|---|
| Email: | anirban.nick@gmail.com |
| Copyright(C): | 2016, Anirban Roy Das <anirban.nick@gmail.com> |
License¶
The MIT License (MIT)
sphinxSimDoc - Collection of simple docs created by Sphinx.
Copyright (c) 2016 Anirban Roy Das <anirban.nick@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy ofthis software and associated documentation files (the “Software”), to deal inthe Software without restriction, including without limitation the rights touse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies ofthe Software, and to permit persons to whom the Software is furnished to do so,subject to the following conditions:The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANT ABILITY, FITNESSFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS ORCOPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHERIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR INCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Overview¶
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.Sphin x is far and away the most popular Python documentation tool. Use it. It converts reStructuredText markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages, and plain text.
reStructuredText¶
Most Python documentation is written with reStructuredText. It’s like Markdown with all the optional extensions built in.
The reStructuredText Primer and the reStructuredText Quick Reference should help you familiarize yourself with its syntax.
Technical Specs¶
| sphinx: | The Documentation building tool |
|---|---|
| python: | The python language implementation |
| pip: | The python package installation tool (Optional but recommended) |
Installation¶
pip install sphinx
In case pip is not installed then you can follow the following methods to install pip.
Pip Installation¶
How to Use¶
This guide will give you information about how to use the documentation to create the same documenation
Step 1
Go to this documenation page and follow the tutorials.
Step 2
Create your own repository just like this sphinxSimDoc repo was created.
Step 3
Use the documentation tutorial to make a new repo having all the rst files included in this repo.
Step 4
Make the docs and you will be able to have your own sampledoc ready
Alternatively¶
Go straight to the index page of this doc and you can follow the instructions from there itself without having to go to the above documentation page.
This page is created in using the earlier mentioned tutorial page. Hence the recursive nature.
sphinxSimDoc¶
A collection of simple docs built from scratch using sampledocs from Sphinx and also by using Sphinx.
Details¶
| Author: | Anirban Roy Das |
|---|---|
| Email: | anirban.nick@gmail.com |
| Copyright(C): | 2016, Anirban Roy Das <anirban.nick@gmail.com> |
Check sphinxSimDoc/LICENSE file for full Copyright notice.
Overview¶
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.
Sphinx is far and away the most popular Python documentation tool. Use it. It converts reStructuredText markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages, and plain text.
reStructuredText¶
Most Python documentation is written with reStructuredText. It’s like Markdown with all the optional extensions built in.
The reStructuredText Primer and the reStructuredText Quick Reference should help you familiarize yourself with its syntax.
Technical Specs¶
| sphinx: | The Documentation building tool |
|---|---|
| python: | The python language implementation |
| pip: | The python package installation tool (Optional but recommended) |
Installation¶
pip install sphinx
For installing pip, follow the bellow methods:
- Method 1 - https://pip.pypa.io/en/stable/installing/
- Method 2 - http://ask.xmodulo.com/install-pip-linux.html
- Method 3 - If you installed python on MAC OS X via
brew install python, then pip is already installed along with python.
Usage¶
Go to the documentation page created by this documentation itself, its recursive, but the documentation helps in created this doumentation itself.
TODO¶
- Add Blog Post regarding this topic.
Getting started¶
Installing your doc directory¶
You may already have sphinx sphinx installed – you can check by doing:
python -c 'import sphinx'
If that fails grab the latest version of and install it with:
> sudo easy_install -U Sphinx
Now you are ready to build a template for your docs, using sphinx-quickstart:
> sphinx-quickstart
accepting most of the defaults. I choose “sampledoc” as the name of my project. cd into your new directory and check the contents:
home:~/tmp/sampledoc> ls
Makefile _static conf.py
_build _templates index.rst
The index.rst is the master ReST for your project, but before adding anything, let’s see if we can build some html:
make html
If you now point your browser to _build/html/index.html, you
should see a basic sphinx site.
Fetching the data¶
Now we will start to customize out docs. Grab a couple of files from
the web site
or git. You will need getting_started.rst and
_static/basic_screenshot.png. All of the files live in the
“completed” version of this tutorial, but since this is a tutorial,
we’ll just grab them one at a time, so you can learn what needs to be
changed where. Since we have more files to come, I’m going to grab
the whole git directory and just copy the files I need over for now.
First, I’ll cd up back into the directory containing my project, check
out the “finished” product from git, and then copy in just the files I
need into my sampledoc directory:
home:~/tmp/sampledoc> pwd
/Users/jdhunter/tmp/sampledoc
home:~/tmp/sampledoc> cd ..
home:~/tmp> git clone https://github.com/matplotlib/sampledoc.git tutorial
Cloning into 'tutorial'...
remote: Counting objects: 87, done.
remote: Compressing objects: 100% (43/43), done.
remote: Total 87 (delta 45), reused 83 (delta 41)
Unpacking objects: 100% (87/87), done.
Checking connectivity... done
home:~/tmp> cp tutorial/getting_started.rst sampledoc/
home:~/tmp> cp tutorial/_static/basic_screenshot.png sampledoc/_static/
The last step is to modify index.rst to include the
getting_started.rst file (be careful with the indentation, the
“g” in “getting_started” should line up with the ‘:’ in :maxdepth:
Contents:
.. toctree::
:maxdepth: 2
getting_started.rst
and then rebuild the docs:
cd sampledoc
make html
When you reload the page by refreshing your browser pointing to
_build/html/index.html, you should see a link to the
“Getting Started” docs, and in there this page with the screenshot.
Voila!
Note we used the image directive to include to the screenshot above with:
.. image:: _static/basic_screenshot.png
Next we’ll customize the look and feel of our site to give it a logo, some custom css, and update the navigation panels to look more like the sphinx site itself – see Customizing the look and feel of the site.
Customizing the look and feel of the site¶
The sphinx site itself looks better than
the sites created with the default css, so here we’ll
invoke T. S. Eliot’s maxim “Talent imitates, but genius steals” and
grab their css and part of their layout. As before, you can either
get the required files _static/default.css and
_templates/layout.html from the website or git (see
Fetching the data). Since I did a git clone before, I will
just copy the stuff I need from there:
home:~/tmp/sampledoc> cp ../sampledoc_tut/_static/default.css _static/
home:~/tmp/sampledoc> cp ../sampledoc_tut/_templates/layout.html _templates/
home:~/tmp/sampledoc> ls _static/ _templates/
_static/:
basic_screenshot.png default.css
_templates/:
layout.html
Sphinx will automatically pick up the css and layout html files since
we put them in the default places with the default names, but we have
to manually edit the top of layout.html to style the title.
Let’s take a look at the layout file: the first part puts a horizontal
navigation bar at the top of our page, like you see on the sphinx and matplotlib sites, the second part includes
a title that when we click on it will take us home and the last part
moves the vertical navigation panels to the right side of the page:
{% extends "!layout.html" %}
{% block rootrellink %}
<li><a href="{{ pathto('index') }}">home</a>| </li>
<li><a href="{{ pathto('search') }}">search</a>| </li>
{% endblock %}
{% block relbar1 %}
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="{{ pathto('index') }}"><h1 style="font-size: 3em;">Sampledoc</h1></a>
</div>
{{ super() }}
{% endblock %}
{# put the sidebar before the body #}
{% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %}
Once you rebuild the site with a make html and reload the page in your browser, you should see a fancier site that looks like this
