# How to Write a Book with Python and Sphinx

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.1constructing [mo]: targets for 0 po recordsdata which will likely be outdatedconstructing [html]: targets for 1 supply recordsdata which will likely be outdatedupdating ambiance: [new config] 1 added, 0 changed, 0 eliminatedreading sources... [100%] index taking a survey now-outdated recordsdata... none stumbled onpickling ambiance... accomplishedchecking consistency... accomplishedpreparing paperwork... accomplishedwriting output... [100%] index generating indices... genindexdonewriting additional pages... searchdonecopying static recordsdata... ... accomplishedcopying additional recordsdata... accomplisheddumping search index in English (code: en)... accomplisheddumping object inventory... accomplishedblueprint 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):

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 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 leetcodeIndices 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 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!