How to Write a Book with Python and Sphinx

0

Image for post

Image for post

Photo by Theme Inn on Unsplash

Are searching to jot down a technical e-book or file your challenge?

Here I’ll stroll you by strategy of the arrangement in which you would maybe well get that with python and sphinx. You would also blueprint thunder of tables that might maybe salvage sections to the chapters of your e-book. I will display you a case gaze to know get out how to insert photos, hyperlinks, mathematical system, syntax highlighting to your popular programming languages, and extra.

Assuming you would maybe well also goal have some recent recordsdata of python, let’s dive in and peek what sphinx can get for us.

Sphinx is a documentation generator library which is in a plot to be precious to generate documentation to your challenge and can also be extinct for growing a thunder (e.g. a e-book) in a LaTeX and then will likely be transformed to PDF layout.‍

Whether or now not you thunder macOS, Linux, or Windows you would maybe well set up it with this insist:

$ pip set up -U sphinx

otherwise you would maybe well consult with sphinx doc whenever you happen to love to have extra alternate choices.

Let’s first make sure sphinx is attach in by showing its version:

$ sphinx-quickstart --version

If now we have got the version number, we’re right to fling and form our challenge itemizing that must unexcited salvage the documentation that we desire:

$ mkdir sphinx-tutorial && cd sphinx-tutorial

$ sphinx-quickstart

Now, a bunch of recordsdata will likely be generated by sphinx’s aspect including a makefile .. we need to separate the somewhat a diffusion of recordsdata into supply itemizing and blueprint itemizing. The availability dir contains the configurations of our challenge whereas the blueprint dir contains nothing now but after we blueprint our challenge we must unexcited peek the rendered documentation constructed there.

Let’s peek the configurations we’ve accomplished to this level by opening config.py within the availability itemizing:

You would also alternate any of the variables within the configuration file but let’s follow the challenge recordsdata for now that you would maybe well alternate in this file or at the origin after we did the sphinx-quickstart insist.

Let’s blueprint the documentation and peek what we are capable of gain within the blueprint itemizing and what our sphinx quickstart boilerplate discover love within the rep:

$ sphinx-blueprint supply/ blueprint/

And here is the output at the insist line:

Working Sphinx v3.2.1

constructing [mo]: targets for 0 po recordsdata which will likely be outdated

constructing [html]: targets for 1 supply recordsdata which will likely be outdated

updating ambiance: [new config] 1 added, 0 changed, 0 eliminated

reading sources... [100%] index

taking a survey now-outdated recordsdata... none stumbled on

pickling ambiance... accomplished

checking consistency... accomplished

preparing paperwork... accomplished

writing output... [100%] index

generating indices... genindexdone

writing additional pages... searchdone

copying static recordsdata... ... accomplished

copying additional recordsdata... accomplished

dumping search index in English (code: en)... accomplished

dumping object inventory... accomplished

blueprint succeeded.
The HTML pages are in blueprint.

So the second argument of sphinx-blueprint is the availability itemizing which contains config.py and index.rst and the third argument is the blueprint itemizing which must unexcited salvage the exported recordsdata and folders. Let’s explore what’s within the blueprint dir now:

├── blueprint

│ ├── _sources

│ │ └── index.rst.txt

│ ├── _static

│ │ ├── alabaster.css

│ │ ├── recent.css

│ │ ├── customized.css

│ │ ├── doctools.js

│ │ ├── documentation_options.js

│ │ ├── file.png

│ │ ├── jquery-3.5.1.js

│ │ ├── jquery.js

│ │ ├── language_data.js

│ │ ├── minus.png

│ │ ├── plus.png

│ │ ├── pygments.css

│ │ ├── searchtools.js

│ │ ├── underscore-1.3.1.js

│ │ └── underscore.js

│ ├── genindex.html

│ ├── index.html

│ ├── objects.inv

│ ├── search.html

│ └── searchindex.js

It has two directories and some recordsdata in its maintain direction, let’s focal level now on index.html due to the here is the rendered HTML file that you would maybe well peek on the rep showing the quickstart file. How will we peek it? by simply copying its direction and then pasting it on the URL.

Or you would maybe well get it by strategy of the terminal; a insist and then the path to that index file

For macOS customers:

$ originate blueprint/index.html

For Linux customers:

$ xdg-originate blueprint/index.html

For Windows customers:

$ commence blueprint/index.html

Here is what you would maybe well peek on the rep (regionally):

Image for post

Image for post

sphinx quickstart webpage

As you would maybe well peek, the URL is the plump direction of my index file residing regionally regionally. Let’s peek how we are capable of edit the thunder of this webpage and what textual language we are capable of thunder for that.

reStructuredText is a markup language designed to be straightforward and unobtrusive. It uses constant patterns interpreted by an HTML converter to form ‘Very Structured Textual thunder’ that is also extinct by a net based browser. Its layout is .rst

Let’s edit the most valuable file index.rst which exists within the availability itemizing:

.. myproject documentation master file, created by

sphinx-quickstart on Sat Aug 29 14: 31: 34 2020.

You would also adapt this file fully to your liking, on the assorted hand it will unexcited as a minimal

salvage the foundation `toctree` directive.
Welcome to myproject's documentation!

=====================================
.. toctree::

:maxdepth: 2

:caption: Contents:
Indices and tables

==================
:ref:`genindex`

:ref:`modindex`

:ref:`search`

Let’s order, I’d expend to snatch the Search Web page titles and attach away with the Index and Module Index titles. We can get so by deleting these two lines:

:ref:`genindex`

:ref:`modindex`

Let’s blueprint again and peek what if that solved our anguish:

$ sphinx-blueprint supply/ blueprint/

Seems find it irresistible did

Image for post

Image for post

sphinx documentation with out indexes

Let’s order, we’d expend to reproduction what’s in my old watermelon anguish fixing weblog put up and get it the usage of reStructuredText. How will we form a hyperlink and get out how to manufacture the tiny headers and at the quit we desire to jot down the python and javascript code with a syntax highlighter. Let’s get it

First, we must unexcited form rst know that there is a folder that might maybe salvage such weblog put up and is even handed as within the table of contents. Within the index.rst we imprint there might be a construction for the table of contents starting up with toctree which is a sphinx directive which implies it will add relations between the one recordsdata the file is manufactured from. In our case, we desire to add a file known as codeforces which contains the watermelon weblog put up:

.. toctree:: 

:maxdepth: 2

:caption: Contents:
codeforces

But where is the codeforces file? It might maybe well unexcited exist within the availability itemizing (at the identical stage of the most valuable RST file) so now the availability itemizing tree must unexcited discover love this:

└── supply

├── _static

├── _templates

├── codeforces.rst

├── conf.py

└── index.rst

If you happen to happen to thought fully elated number, a medium leetcode anguish that I placed on my weblog .. you’ll peek it has some mathematical system there — straightforward ones .. let’s peek how we are capable of render math equations in reStructuredText.

First we need to let the configuration file know that we desire to position some math there and that’s within the config.py by enable MathJax in Sphinx which enable us to jot down LaTeX. In represent to get that, we can add this sphinx.ext.mathjax to the list of extensions:

extensions = ['sphinx.ext.mathjax']

We’d expend to add leetcode within the contents after codeforces, so we must unexcited add that within the index.rst so this file now appears to be like to be like love

.. myproject documentation master file, created by

sphinx-quickstart on Sat Aug 29 14: 31: 34 2020.

You would also adapt this file fully to your liking, on the assorted hand it will unexcited as a minimal

salvage the foundation `toctree` directive.
Welcome to myproject's documentation!

=====================================
.. toctree::

:maxdepth: 2

:caption: Contents:
codeforces

leetcode
Indices and tables

==================
:ref:`search`

Adding leetcode RST script you would maybe well peek the uncooked script from clicking uncooked at the bottom:

Now we are capable of peek that we are capable of write mathematical system, code-blocks, and extra

Image for post

Image for post

sphinx documentation with mathematical system and code-blocks

At some level, we might maybe well expend to remodel that RST documentation into PDF. Sooner than we blueprint, we need to configure that within the extension so we add rst2pdf.pdfbuilder so now the extension list discover love this:

extensions = ['sphinx.ext.mathjax', 'rst2pdf.pdfbuilder']

One thing then it be a need to to alternate is the builder form by the selection -b in sphinx-blueprint insist line:

$ sphinx-blueprint -b pdf supply/ blueprint/

you’ll peek an error due to the it’s now not attach in but, get so with pip and then try again:

$ pip set up rst2pdf

Now, you would maybe well thunder python and sphinx to blueprint a documentation to your challenge with table of contents and you would maybe well thunder hyperlinks, headings, photos, mathematical system, syntax highlighting for no matter programming languages you love, and extra.

And now not gleaming a documentation, you would maybe well also write a technical e-book.

Thank you for reaching here!

Read More

Leave A Reply

Your email address will not be published.