We make a textbook or documentation for an hour on the Sphinx
I teach web programming. When you teach people, the saying “shoemaker without shoes” should not apply to you: you should do everything without visible effort and quickly. The textbook should be easy and simple, and look good.
In general, if you need to make a documentation, tutorial, or just a set of texts with illustrations, then you need Python Sphinx , and here I will tell you how to quickly configure and use it.
')
On the Windows platform, you will need Python, and I’ll leave it to you as your homework. In addition to Python, you need the distribute and curl (or wget) packages. Download and install distribute and pip :
Now you can install Sphinx itself:
* in ubuntu / debian add sudo
After that, it is enough to create a folder for the project and run the sphinx-quickstart script in it. He will ask a few questions. Of these, in my opinion, you have to answer two differently:
Procurement project is ready. Then you can open index.rst and try to edit.
How to study the markup ReStructured Text? Good software does not require reading the documentation. Sphinx is no exception: on all pages made by him there is a link “Show source code” (“Show source”) . Peering into other people's sources, you can learn a lot and quickly. Watch and experiment.
Having written something significant, we run the HTML assembly in the console:
Open the index.html page from the _build / html folder and enjoy it. We have a static site with a search (in JavaScript).
Finally, when we began to edit the files, it turns out that every time to run make html and update the browser is a very tedious task. The inotify package allows you to monitor file changes and run commands. Install infotify-tools and xdotool:
The simplest version of the script, tracking updates. It launches the assembly of multipage html documentation and a single file, then presses the F5 button in Chrome in the open tab:
But it quickly turns out to be a flaw: how many files are updated, so many times and the build starts. It is necessary to group similar events in one. Searching for various options, I decided not to write my script on Python, but to get by with a shell script that was run from the project folder:
He compares the time of the event with the time when the turn came to him. If the event happened 1-2 seconds ago, then you need to re-create the documentation. In order for other systems to finish their work (for example, hg update is over), the script sleeps for 1 second. The build begins. After that, the following events are processed, and they will be very old, so the script skips them right away.
You can also embed it in the Makefile:
Sphinx can do multi-page HTML, can make a single file, as well as PDF, e-books (EPUB) and someone made CHM.
There are 2 ways to make a PDF: install Latex by pumping out 1 GB of packages, but the output will be a pouch. Another option is the new Python package rst2pdf, which is fast and simple; it will issue a PDF of a very simple look. Above him will have to work hard to bring the style to decent.
I add a link to download PDF on the main page, this is the download instruction. So that it is not visible in the PDF itself, there is only a block:
Attention: when Sphinx collects HTML, it will copy this file to the static folder. Therefore, in order for the versions to match, you must first generate a PDF, only then HTML.
There are 3 options. The simplest thing is to upload the project to BitBucket , add the free Read The Docs service to the repository, then register on ReadTheDocs and create a project there. When you upload new revisions in the main branch, RTD will download them and redo the documentation. Thus, the documentation for the program library does not need to be specifically dealt with: it is sufficient to keep up to date the dostrings.
If you want to keep a closed site for your own, you can make a simple password-protected site and collect it manually. It is enough to upload the contents of the _build / html folder to the root of the site. I use rsync for this and wrote 2 lines in the Makefile:
First, the documentation will be compiled in latexpdf format, then in html (and PDF will be added to the “download”), then rsync will upload the files to the hosting by deleting the old ones (option - delete).
If you need your own closed system that does not depend on others, you can run the ReadTheDocs clone.
Sphinx uses “themes”, these are Jinja templates plus static files, folded into one folder. I posted a few collected from the free access to those . To enable a theme, you need to configure 2 conf.py lines:
Result:
Sphinx is a very powerful tool that can make you a static site from a minimum of data. For a lot of static text and photos, this is the best option. It can be quickly raised and updated very quickly. And the documentation for software libraries will be collected at all by itself without your efforts - just a developer’s dream!
PS I forgot to add examples of how to make automatic documentation. In fact, the settings and source code can be peeped in any project, and it is also useful to know sphinx-apidoc .
Adding on 10/11/12: on GitHub I found the preformatted table editor for SublimeText, made especially for those who edit RST and Markdown.
In general, if you need to make a documentation, tutorial, or just a set of texts with illustrations, then you need Python Sphinx , and here I will tell you how to quickly configure and use it.
')
Install Python and tools
On the Windows platform, you will need Python, and I’ll leave it to you as your homework. In addition to Python, you need the distribute and curl (or wget) packages. Download and install distribute and pip :
curl http://python-distribute.org/distribute_setup.py | python curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python Now you can install Sphinx itself:
pip install sphinx
* in ubuntu / debian add sudo
Create a draft textbook
After that, it is enough to create a folder for the project and run the sphinx-quickstart script in it. He will ask a few questions. Of these, in my opinion, you have to answer two differently:
> Separate source and build directories (y/N) [n]: y ( - ) > Create Windows command file? (Y/n) [y]: n ( .bat, - , Linux)
Procurement project is ready. Then you can open index.rst and try to edit.
How to study the markup ReStructured Text? Good software does not require reading the documentation. Sphinx is no exception: on all pages made by him there is a link “Show source code” (“Show source”) . Peering into other people's sources, you can learn a lot and quickly. Watch and experiment.
Having written something significant, we run the HTML assembly in the console:
make html
Open the index.html page from the _build / html folder and enjoy it. We have a static site with a search (in JavaScript).
Auto assembly
Finally, when we began to edit the files, it turns out that every time to run make html and update the browser is a very tedious task. The inotify package allows you to monitor file changes and run commands. Install infotify-tools and xdotool:
sudo apt-get install inotify-tools xdotool
The simplest version of the script, tracking updates. It launches the assembly of multipage html documentation and a single file, then presses the F5 button in Chrome in the open tab:
inotifywait -mr source --exclude _build -e close_write -e create -e delete -e move | while read file event; do make singlehtml html xdotool search --name Chromium key --window %@ F5 done
But it quickly turns out to be a flaw: how many files are updated, so many times and the build starts. It is necessary to group similar events in one. Searching for various options, I decided not to write my script on Python, but to get by with a shell script that was run from the project folder:
inotifywait -mr source --exclude _build -e close_write -e create -e delete -e move --format '%w %e %T' --timefmt '%H%M%S' | while read file event tm; do current=$(date +'%H%M%S') delta=`expr $current - $tm` if [ $delta -lt 2 -a $delta -gt -2 ] ; then sleep 1 # 1 make html singlehtml xdotool search --name Chromium key --window %@ F5 fi done
He compares the time of the event with the time when the turn came to him. If the event happened 1-2 seconds ago, then you need to re-create the documentation. In order for other systems to finish their work (for example, hg update is over), the script sleeps for 1 second. The build begins. After that, the following events are processed, and they will be very old, so the script skips them right away.
You can also embed it in the Makefile:
.PHONY autobuild autobuild: <>
Documentation formats
Sphinx can do multi-page HTML, can make a single file, as well as PDF, e-books (EPUB) and someone made CHM.
There are 2 ways to make a PDF: install Latex by pumping out 1 GB of packages, but the output will be a pouch. Another option is the new Python package rst2pdf, which is fast and simple; it will issue a PDF of a very simple look. Above him will have to work hard to bring the style to decent.
Download documentation in PDF
I add a link to download PDF on the main page, this is the download instruction. So that it is not visible in the PDF itself, there is only a block:
.. only:: html :download:` PDF <../build/latex/manual.pdf>`.
Attention: when Sphinx collects HTML, it will copy this file to the static folder. Therefore, in order for the versions to match, you must first generate a PDF, only then HTML.
Publication
There are 3 options. The simplest thing is to upload the project to BitBucket , add the free Read The Docs service to the repository, then register on ReadTheDocs and create a project there. When you upload new revisions in the main branch, RTD will download them and redo the documentation. Thus, the documentation for the program library does not need to be specifically dealt with: it is sufficient to keep up to date the dostrings.
If you want to keep a closed site for your own, you can make a simple password-protected site and collect it manually. It is enough to upload the contents of the _build / html folder to the root of the site. I use rsync for this and wrote 2 lines in the Makefile:
.PHONY: sync sync: latexpdf html rsync -ave ssh build/html/ siberiano@hosting:/home/siberiano/webapps/course_manual/ --delete
First, the documentation will be compiled in latexpdf format, then in html (and PDF will be added to the “download”), then rsync will upload the files to the hosting by deleting the old ones (option - delete).
If you need your own closed system that does not depend on others, you can run the ReadTheDocs clone.
Beautiful design
Sphinx uses “themes”, these are Jinja templates plus static files, folded into one folder. I posted a few collected from the free access to those . To enable a theme, you need to configure 2 conf.py lines:
html_theme = 'armstrong' # html_theme_path = ['themes'] # source,
Result:
Summary
Sphinx is a very powerful tool that can make you a static site from a minimum of data. For a lot of static text and photos, this is the best option. It can be quickly raised and updated very quickly. And the documentation for software libraries will be collected at all by itself without your efforts - just a developer’s dream!
PS I forgot to add examples of how to make automatic documentation. In fact, the settings and source code can be peeped in any project, and it is also useful to know sphinx-apidoc .
Adding on 10/11/12: on GitHub I found the preformatted table editor for SublimeText, made especially for those who edit RST and Markdown.
Source: https://habr.com/ru/post/151129/
All Articles