xn3.wiki documentation
Post on 20-Mar-2022
28 Views
Preview:
TRANSCRIPT
XN3.wiki DocumentationRelease 0.0.1
Marcel Buehring
June 07, 2016
Contents
1 Docker 11.1 Docker cheats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Linux 52.1 CentOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Debian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.4 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.5 Red Hat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.6 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3 Mac OS X 133.1 Airport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4 NFS 154.1 NFS cheats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5 Sphinx 175.1 Why Sphinx and for which users ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.2 Restructured Text (reST) and Sphinx CheatSheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6 Python 356.1 Python cheats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
7 Sphinx 37
8 Vim 398.1 Vim cheats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Bibliography 41
Python Module Index 43
i
ii
CHAPTER 1
Docker
1.1 Docker cheats
1.1.1 Container
• start a container
docker start <id or name>
• restart a container
docker restart <id or name>
• stop a container
docker stop <id or name>
• remove a container
docker rm <id or name>
• create & Run an interactive docker shell
docker run -i -t <image> /bin/docker
• create & Run a command in background
docker run -d <image> <cmd>
• list the running containers
docker ps
• list all containers
docker ps -a
• open a shell in running container
docker exec -i -t <id or name> /bin/docker
• show container details
docker inspect <id or name>
• show container events
1
XN3.wiki Documentation, Release 0.0.1
docker events <id or name>
• show container ports
docker ports <id or name>
• show changed files
docker diff <id or name>
• show container processes
docker top <id or name>
• show container logs
docker logs <id or name>
• stream container logs
docker logs -f <id or name>
• copy file from container
docker cp <id or name>:<source> ,<destination>
• export container
docker export <id or name> > <tar file>
1.1.2 Images
• list local images
docker images
• pull official image
docker pull <name>
• pull inofficial image
docker pull <namespace>/<name>
• push image to DockerHub
docker push <namespace>/name>
• create image from dockerfile
docker build <path>
• delete image
docker rmi <name>
• show image history
docker history <name>
• show image details
2 Chapter 1. Docker
XN3.wiki Documentation, Release 0.0.1
docker inspect <name>
• tag image
docker tag <id> <namespace>/<name>:<tag>
• search for image
docker search <query>
1.1. Docker cheats 3
XN3.wiki Documentation, Release 0.0.1
4 Chapter 1. Docker
CHAPTER 2
Linux
2.1 CentOS
2.1.1 Red Hat boot
Enable verbose boot on Red Hat like distros
Remove the rhgb and quiet grub arguments to enable a verbose text boot.
• RHEL6 (grub)
sed -i 's/rhgb\|quiet//g' /boot/grub/grub.conf
• RHEL7 (grub2)
sed -i 's/rhgb\|quiet//g' /etc/default/grub && grub2-mkconfig -o /boot/grub2/grub.cfg
On multiple Systems
• RHEL6 (grub)
for SYSTEM in SYSTEM1 SYSTEM2 SYSTEM3 SYSTEM4 ; dossh ${SYSTEM} 'sed -i "s/rhgb\|quiet//g" /boot/grub/grub.conf'
done
• RHEL7 (grub2)
while read -r SYSTEM ; dossh ${SYSTEM} 'sed -i "s/rhgb\|quiet//g" /etc/default/grub \
&& grub2-mkconfig -o /boot/grub2/grub.cfg'done <<< ${SYSTEMS_LIST}
During kickstart installation
• RHEL6 (grub)
%post --log=/root/postinstall.logsed -i 's/rhgb\|quiet//g' /boot/grub/grub.conf
• RHEL7 (grub2)
5
XN3.wiki Documentation, Release 0.0.1
%post --log=/root/postinstall.logsed -i 's/rhgb\|quiet//g' /etc/default/grubgrub2-mkconfig -o /boot/grub2/grub.cfg
2.1.2 yum
• Install a specific version of package
# show last three versionsyum --showduplicates list gitlab-ce | tail -n 3
# install specific package versionyum install <package name>-<version info>
• Remove old kernels
# install prerequisitesyum install yum-utils
# set count as how many old kernels you want leftpackage-cleanup --oldkernels --count=2
2.2 Debian
2.2.1 Kimsufi
Kimsufi-Kernel with Docker support on Debian
• Install dependencies
apt-get install make gcc libncurses5-dev lzma dpkg-dev linux-source
• Download latest-production config
wget ftp://ftp.ovh.net/made-in-ovh/bzImage/latest-production/config-3.14.32-xxxx-std-ipv6-64 -O /boot/config-3.14.32-xxxx-std-ipv6-64
See also:
Latest stable Kimsufi-Kernels and related configs -> ftp://ftp.ovh.net/made-in-ovh/bzImage/latest-production
Build with new docker enabled kernel config
cd /usr/src/tar xvf linux-source-3.16.tar.xzcp /boot/config-3.14.32-xxxx-std-ipv6-64 linux-source-3.16/.configcd /usr/src/linux-source-3.16make oldconfig
# configure as listed belowmake menuconfig
# ---- snip -------------------------------------------General setup --->
6 Chapter 2. Linux
XN3.wiki Documentation, Release 0.0.1
[*] Control Group support --->[*] Example debug cgroup subsystem[*] Freezer cgroup subsystem[*] Device controller for cgroups[*] Cpuset support[*] Include legacy /proc//cpuset file[*] Simple CPU accounting cgroup subsystem[*] Resource counters[*] Memory Resource Controller for Control Groups[*] Memory Resource Controller Swap Extension[*] Memory Resource Controller Swap Extension enabled[...][*] Memory Resource Controller Kernel Memory accountin[...][*] Enable perf_event per-cpu per-container group cgrou[...][*] Group CPU scheduler --->[*] Group scheduling for SCHED_OTHER (NEW)[*] CPU bandwidth provisioning for FAIR_GROUP_SCHED[*] Group scheduling for SCHED_RRFIFO[*] Block IO controller[*] Enable Block IO controller debugging-*- Namespaces support --->[*] UTS namespace[*] IPC namespace[*] PID Namespaces[*] Network namespace[*] Enable loadable module supportNetworking support --->Networking options ---><*> 802.1d Ethernet Bridging[*] IGMPMLD snooping[*] VLAN filtering<*> 802.1Q/802.1ad VLAN Support[*] GVRP GARP VLAN Registration Protocol supportDevice Drivers --->[*] Network device support ---><*> MAC-VLAN support<*> MAC-VLAN based tap driver<*> Virtual ethernet pair deviceCharacter devices --->-*- Unix98 PTY support[*] Support multiple instances of devpts# ---- snap -------------------------------------------
make deb-pkg LOCALVERSION=-xovh-docker KDEB_PKGVERSION=1 --jobs 2 | tee -a build.log
Rebuild with already docker enabled kernel config
cd /usr/src/tar xvf linux-source-3.16.tar.xzcp /boot/config-3.16.*-ipv6-64-xovh-docker linux-source-3.16/.configcd /usr/src/linux-source-3.16make oldconfigmake deb-pkg LOCALVERSION=-xovh-docker KDEB_PKGVERSION=1 --jobs 2 | tee -a build.log
2.2. Debian 7
XN3.wiki Documentation, Release 0.0.1
2.3 Hardware
2.3.1 Function keys (fn)
Apple Keyboards
Available modes
mode description0 disable fn-key completely1 enable fn-key (shortcut keys first)2 enable fn-key (F# keys first - F1-F12)
• set temporary default mode (immediately active)
echo 2 > /sys/module/hid_apple/parameters/fnmode
• set permanent default mode (active after reboot)
echo 'options hid_apple fnmode=2' > /etc/modprobe.d/50-hid_apple.conf
# debian, ubuntu, ...update-initramfs -u ; sync
# rhel, centos, fedora, ...dracut -f ; sync
2.3.2 Skylake
With a Skylake under a Linux kernel must the Intel Graphics Installer for Linux necessarily be installed!
Currently supported Distributions
• Ubuntu 15.10 (Wily Werewolf) 32/64-bit
• Fedora 23 32/64-bit
Hardware related problems and their solutions
Intel NUC6i5SYK
Desktop show glitches, freeze complete or repeatedly for short times.
Solution: Boot the Kernel with i915.enable_rc6=0
Lenovo ThinkPad X1 Carbon & Yoga 260
After dist-upgrade from Ubuntu 15.4 on 15.10 (with Kernel 4.2), the system remains hanging at boot with black screen.
Solution: Boot the Kernel with intel_pstate=no_hwp or intel_pstate=skylake_hwp
8 Chapter 2. Linux
XN3.wiki Documentation, Release 0.0.1
2.3.3 Storage
• how to check if an HDD or SSD
# 0 == SSD / 1 == HDDcat /sys/block/sda/queue/rotational
# ROTA: 0 == SSD / 1 == HDDlsblk -d -o name,rota
2.4 Network
2.4.1 Bonding
• check the status of a bond and his slaves
• show the real mac adresses of the slaves
cat /proc/net/bonding/bond0
2.4.2 Linux network cheats
• get default gateway
ip route | awk '/^default via/{print $3}'
2.4.3 ipcalc
• validate ip address
ipcalc -c 172.16.0.20/29
• calculate prefix
ipcalc -p 172.16.0.20 255.255.255.248
• calculate netmask
ipcalc -m 172.16.0.20/29
• calculate network-id
ipcalc -n 172.16.0.20/29
ipcalc -n 172.16.0.20 255.255.255.248
• calculate broadcast
ipcalc -b 172.16.0.20/29
ipcalc -b 172.16.0.20 255.255.255.248
2.4. Network 9
XN3.wiki Documentation, Release 0.0.1
2.4.4 Hardware address
Generate a valid hardware address
• oVirt/KVM/Xen (00:16:3E) like hardware address
echo 00:16:3E$(od -N3 -tx1 -An /dev/random |sed 's/ /:/g')
Useful online tools
• Vendor Lookup: http://www.miniwebtool.com/mac-address-lookup/
• Address Generator: http://www.miniwebtool.com/mac-address-generator/
2.5 Red Hat
2.6 Tools
2.6.1 etckeeper
etckeeper is a collection of tools to let /etc be stored in a git, mercurial, bazaar or darcs repository. This lets youuse git to review or revert changes that were made to /etc. Or even push the repository elsewhere for backups orcherry-picking configuration changes.
It hooks into package managers like apt to automatically commit changes made to /etc during package upgrades.It tracks file metadata that git does not normally support, but that is important for /etc, such as the permissions of/etc/shadow.
It’s quite modular and configurable, while also being simple to use if you understand the basics of working withversion control.
I think it’s the best utility from Joey Hess. At this point a big thanks to Joey!
Setup on Debian
## install debian packageapt-get install etckeeper
## minimal user git config (~/.gitconfig)git config --global user.name "${USER:=${LOGNAME}}@$(hostname -s|tr A-Z a-z)"git config --global user.email "${USER:=${LOGNAME}}@$(hostname -d|tr A-Z a-z)"git config --global push.default simple
# show user git configgit config --global -l
# set backup repositorysed -i '/^PUSH_REMOTE=/,0{s/".*"/"backup"/}' /etc/etckeeper/etckeeper.conf
## reinitialize manually (clean start)etckeeper uninit -f && etckeeper init
10 Chapter 2. Linux
XN3.wiki Documentation, Release 0.0.1
## add remote backup repositorygit -C /etc remote add backup git@xn3.codes:infra/$(hostname -s|tr A-Z a-z)-etc.git
## push initial commitetckeeper commit 'Initial commit'
## add upstream for manually pushinggit push -u backup master
2.6. Tools 11
XN3.wiki Documentation, Release 0.0.1
12 Chapter 2. Linux
CHAPTER 3
Mac OS X
3.1 Airport
• Link hidden airport cli
sudo ln -si /System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport /usr/local/bin/
• Get osx to pick strongest AP with identical SSID
sudo airport prefs JoinMode=Strongest
13
XN3.wiki Documentation, Release 0.0.1
14 Chapter 3. Mac OS X
CHAPTER 4
NFS
4.1 NFS cheats
4.1.1 Client
• view available exports on an NFS server
showmount -e <fqdn or ip>
15
XN3.wiki Documentation, Release 0.0.1
16 Chapter 4. NFS
CHAPTER 5
Sphinx
5.1 Why Sphinx and for which users ?
Sphinx requires to learn a language called ReST or RST that stands for restructured Text. To get an idea of thesyntax, click on the show Source link in the right side bar, in any page.
The advantage of the ReST syntax resides in its human-readable nature, which makes it useful to include inside yoursource code (e.g. docstrings in Python). Taking notes in ReST language is also conveninent since it remains readablebut can be also interpreted later into nice layout (pdf, html, ...).
ReST and Sphinx provides a rich syntax made of directives. Sphinx comes with many of them in addition to standardones provided by the ReST language. For instance, you can include LaTeX code for your equations. Yet, there aremany directives and extensions, and it is sometimes difficult to figure out their names and options so it may not be foreverybody. However, if you are developer, and especially a Python developer, the investment worths it !!!
These pages give you the elements to start a documentation using Sphinx and provides a summary of directive/optionsgathered in the ReST tutorial section.
Note: I should mention that the Sphinx official page is very well done and improves all the time. I encourage you togo and visit their website of course ! Thanks to the Sphinx developers
5.2 Restructured Text (reST) and Sphinx CheatSheet
Overview
This page describes some of the RST and Sphinx syntax. It is based on resource found at Sphinx , Docutils andmore generally software documentation written with Sphinx.This is not an exhaustive description but it should allow you to start and create already nice documentation.
Date June 07, 2016Author Thomas CokelaerCustomizer Marcel Buehring
Note: The original find you here -> http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
17
XN3.wiki Documentation, Release 0.0.1
Contents
• Restructured Text (reST) and Sphinx CheatSheet– Introduction– Text Formatting
* Inline markup and special characters (e.g., bold, italic, verbatim)* Headings* Internal and External Links* List and bullets
– What are directives– Inserting code and Literal blocks
* How to include simple code* code-block directive* Include code with the literalinclude directive
– Tables* Simple tables* Multicells tables, first method* Multicells table, second method* The tabularcolumns directive* The csv-table directive
– Include other RST files with the toctree directive– Python software
* Auto-document your python code* python docstrings
– Images and figures* Include Images* Include a Figure
– Boxes* Colored boxes: note, seealso, todo and warnings* Topic directive* Sidebar directive
– Others* Comments* Substitutions* glossary, centered, index, download and field list* Footnote* Citations* More about aliases* Intersphinx* file-wide metadata* metainformation* contents directives
– Useful extensions* pngmath: Maths and Equations with LaTeX* TODO extension* copybutton
5.2.1 Introduction
The reStructuredText (RST) syntax provides an easy-to-read, what-you-see-is-what-you-get plaintext markup syntaxand parser system. However, you need to be very precise and stick to some strict rules:
18 Chapter 5. Sphinx
XN3.wiki Documentation, Release 0.0.1
• like Python, RST syntax is sensitive to indentation !
• RST requires blank lines between paragraphs
This entire document is written with the RST syntax. In the right sidebar, you should find a link show source, whichshows the RST source code.
5.2.2 Text Formatting
Inline markup and special characters (e.g., bold, italic, verbatim)
There are a few special characters used to format text. The special character * is used to defined bold and italic textas shown in the table below. The backquote character ‘ is another special character used to create links to internal orexternal web pages as you will see in section Internal and External Links.
usage syntax HTML renderingitalic *italic* italicbold **bold** boldlink ‘python <www.python.org>‘_ pythonverbatim ‘‘*‘‘ *
The double backquote is used to enter in verbatim mode, which can be used as the escaping character. There are somerestrictions about the * and ‘‘ syntax. They
• cannot not be nested,
• content may not start or end with whitespace: * text* is wrong,
• it must be separated from surrounding text by non-word characters like a space.
The use of backslash is a work around to second previous restrictions about whitespaces in the following case:
• this is a *longish* paragraph is correct and gives longish.
• this is a long*ish* paragraph is not interpreted as expected. You should use this is along\ *ish* paragraph to obtain longish paragraph
In Python docstrings it will be necessary to escape any backslash characters so that they actually reach reStructured-Text. The simplest way to do this is to use raw strings by adding the letter r in front of the docstring.
Python string Typical resultr"""\*escape* \‘with‘ "\\"""" *escape* ‘with‘ "\""""\\*escape* \\‘with‘ "\\\\"""" *escape* ‘with‘ "\""""\*escape* \‘with‘ "\\"""" escape with ""
Headings
In order to write a title, you can either underline it or under and overline it. The following examples are correct titles.
*****Title*****
subtitle########
subsubtitle**********************and so on
5.2. Restructured Text (reST) and Sphinx CheatSheet 19
XN3.wiki Documentation, Release 0.0.1
Two rules:
• If under and overline are used, their length must be identical
• The length of the underline must be at least as long as the title itself
Normally, there are no heading levels assigned to certain characters as the structure is determined from the successionof headings. However, it is better to stick to the same convention throughout a project. For instance:
• # with overline, for parts
• * with overline, for chapters
• =, for sections
• -, for subsections
• ^, for subsubsections
• “, for paragraphs
Internal and External Links
In Sphinx, you have 3 type of links:
1. External links (http-like)
2. Implicit links to title
3. Explicit links to user-defined label (e.g., to refer to external titles).
External links
If you want to create a link to a website, the syntax is
`<http://www.python.org/>`_
which appear as http://www.python.org/ . Note the underscore after the final single quote. Since the full name of thelink is not always simple or meaningful, you can specify a label (note the space between the label and link name):
`Python <http://www.python.org/>`_
The rendering is now: Python.
Note: If you have an underscore within the label/name, you got to escape it with a ‘\’ character.
Implicit Links to Titles
All titles are considered as hyperlinks. A link to a title is just its name within quotes and a final underscore:
`Internal and External links`_
This syntax works only if the title and link are within the same RST file. If this is not the case, then you need to createa label before the title and refer to this new link explicitly, as explained in Explicit Links section.
20 Chapter 5. Sphinx
XN3.wiki Documentation, Release 0.0.1
Explicit Links
You can create explicit links within your RST files. For instance, this document has a label at the top calledrst_tutorial, which is specified by typing:
.. _rst_tutorial:
You can refer to this label using two different methods. The first one is:
rst_tutorial_
The second method use the ref role as follows:
:ref:`rst_tutorial`
With the first method, the link appears as rst_tutorial, whereas the second method use the first title’s name found afterthe link. Here, the second method would appear as Restructured Text (reST) and Sphinx CheatSheet.
Note that the second method is compulsary if the link is to be found in an external RST file. For instance, theintroduction page is an external page with a link called introduction at the top of the page. You can jump thereby writting :ref:‘introduction‘, which appears as: Why Sphinx and for which users ?.
Note: Note that if you use the ref role, the final underscore is not required anymore.
List and bullets
The following code:
* This is a bulleted list.
* It has two items, the seconditem uses two lines. (note the indentation)
1. This is a numbered list.2. It has two items too.
#. This is a numbered list.#. It has two items too.
gives:
• This is a bulleted list.
• It has two items, the second item uses two lines. (note the indentation)
1. This is a numbered list.
2. It has two items too.
3. This is a numbered list.
4. It has two items too.
Note: if two lists are separated by a blanck line only, then the two lists are not differentiated as you can see above.
5.2. Restructured Text (reST) and Sphinx CheatSheet 21
XN3.wiki Documentation, Release 0.0.1
5.2.3 What are directives
Sphinx and the RST syntax provides directives to include formatted text. As an example, let us consider the code-blocksyntax. It allows to insert code (here HTML) within your document:
.. code-block:: html:linenos:
<h1>code block example</h1>
Its rendering is:
1 <h1>code block example</h1>
Here, code-block is the name of the directive. html is an argument telling that the code is in HTML format, lineos isan option telling to insert line number and finally after a blank line is the text to include.
Note that options are tabulated.
5.2.4 Inserting code and Literal blocks
How to include simple code
This easiest way to insert literal code blocks is to end a paragraph with the special marker made of a double coulumn::. Then, the literal block must be indented:
This is a simple example::
import mathprint 'import done'
or:
This is a simple example:::
import mathprint 'import done'
gives:
This is a simple example:
import mathprint 'import done'
code-block directive
By default the syntax of the language is Python, but you can specify the language using the code-block directive asfollows:
.. code-block:: html:linenos:
<h1>code block example</h1>
produces
22 Chapter 5. Sphinx
XN3.wiki Documentation, Release 0.0.1
1 <h1>code block example</h1>
Valid values for the highlighting language are all lexer aliases that Pygments supports.
Include code with the literalinclude directive
Then, it is also possible to include the contents of a file as follows:
.. literalinclude:: filename:linenos::language: python:lines: 1, 3-5:start-after: 3:end-before: 5
For instance, the sample.py file contents can be printed:
1 """ here is a dummy documentation"""2 import os3
4
5 def square(a):6 """short description of the function square7
8 longish explanation: returns the square of a: :math:`a^2`9
10 :param a: an input argument11
12 :returns: a*a13 """14 return a*a15
16 assert 4 == square(2)
5.2.5 Tables
There are several ways to write tables. Use standard reStructuredText tables as explained here. They work fine inHTML output, however, there are some gotchas when using tables for LaTeX output.
The rendering of the table depends on the CSS/HTML style, not on sphinx itself.
Simple tables
Simple tables can be written as follows:
+---------+---------+-----------+| 1 | 2 | 3 |+---------+---------+-----------+
which gives:
1 2 3
Size of the cells can be adjusted as follows:
5.2. Restructured Text (reST) and Sphinx CheatSheet 23
XN3.wiki Documentation, Release 0.0.1
+---------------------+---------+---+|1 | 2| 3 |+---------------------+---------+---+
renders as follows:
1 2 3
This syntax is quite limited, especially for multi cells/columns.
Multicells tables, first method
A first method is the following syntax:
+------------+------------+-----------+| Header 1 | Header 2 | Header 3 |+============+============+===========+| body row 1 | column 2 | column 3 |+------------+------------+-----------+| body row 2 | Cells may span columns.|+------------+------------+-----------+| body row 3 | Cells may | - Cells |+------------+ span rows. | - contain || body row 4 | | - blocks. |+------------+------------+-----------+
gives:
Multicells table, second method
The previous syntax can be simplified:
===== ===== ======Inputs Output
------------ ------A B A or B
===== ===== ======False False FalseTrue False True===== ===== ======
gives:
Note: table and latex documents are not yet compatible in sphinx, and you should therefore precede them with the aspecial directive (.. only:: html)
The tabularcolumns directive
The previous examples work fine in HTML output, however there are some gotchas when using tables in LaTeX: thecolumn width is hard to determine correctly automatically. For this reason, the following directive exists:
.. tabularcolumns:: column spec
This directive gives a “column spec” for the next table occurring in the source file. It can have values like:
24 Chapter 5. Sphinx
XN3.wiki Documentation, Release 0.0.1
|l|l|l|
which means three left-adjusted (LaTeX syntax). By default, Sphinx uses a table layout with L for every column. Thiscode:
.. tabularcolumns:: |l|c|p{5cm}|
+--------------+---+-----------+| simple text | 2 | 3 |+--------------+---+-----------+
gives
The csv-table directive
Finally, a convenient way to create table is the usage of CSV-like syntax:
.. csv-table:: a title:header: "name", "firstname", "age":widths: 20, 20, 10
"Smith", "John", 40"Smith", "John, Junior", 20
that is rendered as follows:
Table 5.1: a title
name firstname ageSmith John 40Smith John, Junior 20
5.2.6 Include other RST files with the toctree directive
Sooner or later you will want to structure your project documentation by having several RST files. The toctreedirective allows you to insert other files within a RST file. The reason to use this directive is that RST does not havefacilities to interconnect several documents, or split documents into multiple output files. The toctree directive lookslike
.. toctree:::maxdepth: 2:numbered::titlesonly::glob::hidden:
intro.rstchapter1.rstchapter2.rst
It includes 3 RST files and shows a TOC that includes the title found in the RST documents.
Here are a few notes about the different options
• maxdepth is used to indicates the depth of the tree.
• numbered adds relevant section numbers.
5.2. Restructured Text (reST) and Sphinx CheatSheet 25
XN3.wiki Documentation, Release 0.0.1
• titlesonly adds only the main title of each document
• glob can be used to indicate that * and ? characters are used to indicate patterns.
• hidden hides the toctree. It can be used to include files that do not need to be shown (e.g. a bibliography).
The glob option works as follows:
.. toctree:::glob:
intro*recipe/**
Note also that the title that appear in the toctree are the file’s title. You may want to change this behaviour by changingthe toctree as follows:
.. toctree:::glob:
Chapter1 description <chapter1>
So that the title of this section is more meaningful.
5.2.7 Python software
Sphinx can be used to create generic documentation, or software documentation dedicated to Python, but not only (canC, C++, ...). Here, we’ll focus on Python itself.
Auto-document your python code
Let us suppose you have a python file called sample.py with a function called square. The function’s code is :
1 def square(a):2 """short description of the function square3
4 longish explanation: returns the square of a: :math:`a^2`5
6 :param a: an input argument7
8 :returns: a*a9 """
10 return a*a11
Using the autofunction :
.. currentmodule:: sample
.. autofunction:: square
Gives
sample.square(a)short description of the function square
longish explanation: returns the square of a: 𝑎2
Parameters a – an input argument
26 Chapter 5. Sphinx
XN3.wiki Documentation, Release 0.0.1
Returns a*a
Here, we need to specify in which module should be found the function square, hence the .. module::sampledirective. You can use autoclass and automodule in the same way.
Using the module directive also creates an index (see top right of this page) so it is worth specifying more informationusing platform and synopsis options for example:
.. module:: sample:platform: Unix, Windows:synopsis: sample of documented python code
The results will be shown in a module section (link in top right panel).
Note: the directive module should be use only once for a given module.
Warning: the python code must be in the PYTHONPATH.
See also:
http://sphinx.pocoo.org/markup/desc.html
python docstrings
In a python shell, when you type a statement, it is preceeded by the >>> sign. The results are printed without it. Forinstance:
>>> a = 11
If you want to copy and paste this code, you will get errors since the >>> sign is not part of the syntax. There is ajavascript solution to hide it in the Useful extensions section.
5.2.8 Images and figures
Include Images
Use:
.. image:: stars.jpg:width: 200px:align: center:height: 100px:alt: alternate text
to put an image
5.2. Restructured Text (reST) and Sphinx CheatSheet 27
XN3.wiki Documentation, Release 0.0.1
Include a Figure
.. figure:: stars.jpg:width: 200px:align: center:height: 100px:alt: alternate text:figclass: align-center
figure are like images but with a caption
and whatever else youwish to add
.. code-block:: python
import image
gives
Fig. 5.1: figure are like images but with a captionand whatever else youwish to add
import image
The option figclass is a CSS class that can be tuned for the final HTML rendering.
5.2.9 Boxes
Colored boxes: note, seealso, todo and warnings
There are simple directives like seealso that creates nice colored boxes:
See also:
This is a simple seealso note.
created using:
.. seealso:: This is a simple **seealso** note.
You have also the note directive:
Note: This is a note box.
with
.. note:: This is a **note** box.
and the warning directive:
28 Chapter 5. Sphinx
XN3.wiki Documentation, Release 0.0.1
Warning: note the space between the directive and the text
generated with:
.. warning:: note the space between the directive and the text
There is another todo directive but requires an extension. See Useful extensions
Topic directive
A Topic directive allows to write a title and a text together within a box similarly to the note directive.
This code:
.. topic:: Your Topic Title
Subsequent indented lines comprisethe body of the topic, and areinterpreted as body elements.
gives
Your Topic Title
Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.
Sidebar directive
It is possible to create sidebar using the following code:
.. sidebar:: Sidebar Title:subtitle: Optional Sidebar Subtitle
Subsequent indented lines comprisethe body of the sidebar, and areinterpreted as body elements.
Sidebar Title
Optional Sidebar SubtitleSubsequent indented lines comprise the body of the sidebar, and are interpreted as body elements.
5.2.10 Others
Comments
Comments can be made by adding two dots at the beginning of a line as follows:
.. comments
5.2. Restructured Text (reST) and Sphinx CheatSheet 29
XN3.wiki Documentation, Release 0.0.1
Substitutions
Substitutions are defined as follows:
.. _Python: http://www.python.org/
and to refer to it, use the same syntax as for the internal links: just insert the alias in the text (e.g., Python_, whichappears as Python ).
A second method is as follows:
.. |longtext| replace:: this is a very very long text to include
and then insert |longtext| wherever required.
glossary, centered, index, download and field list
Field list
Whatever this is handy to create new field and the following text is indented
:Whatever: this is handy to create new field
glossary
.. glossary::apical
at the top of the plant.
gives
apical at the top of the plant.
index
.. index::
download
:download:`download samplet.py <sample.py>`
gives download sample.py
hlist directive
hlist can be use to set a list on several columns.
.. hlist::
30 Chapter 5. Sphinx
XN3.wiki Documentation, Release 0.0.1
.. hlist:::columns: 3
* first item
* second item
* 3d item
* 4th item
* 5th item
•first item•second item•3d item•4th item•5th item
Footnote
For footnotes, use [#name]_ to mark the footnote location, and add the footnote body at the bottom of the documentafter a “Footnotes” rubric heading, like so:
Some text that requires a footnote [#f1]_ .
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
You can also explicitly number the footnotes ([1]_) or use auto-numbered footnotes without names ([#]_). Here isan example 1.
Citations
Citation references, like [CIT2002] may be defined at the bottom of the page:
.. [CIT2002] A citation(as often used in journals).
and called as follows:
[CIT2002]_
More about aliases
Directives can be used within aliases:
.. |logo| image:: stars.jpg:width: 20pt:height: 20pt
Using this image alias, you can insert it easily in the text |logo|, like this . This is especially useful when dealing
with complicated code. For instance, in order to include 2 images within a table do as follows:
1 this is a footnote aimed at illustrating the footnote capability.
5.2. Restructured Text (reST) and Sphinx CheatSheet 31
XN3.wiki Documentation, Release 0.0.1
+---------+---------+-----------+| |logo| | |logo| | |longtext||+---------+---------+-----------+
this is a longish text to include within a table and which is longer than the width of the column.
Note: Not easy to get exactly what you want though.
Intersphinx
When you create a project, Sphinx generates a file containing an index to all the possible links (title, classes, functions,...).
You can refer to those index only if Sphinx knowns where to find this index. THis is possible thanks to the intersphinxoption in your configuration file.
For instance, Python provides such a file, by default Sphinx knows about it. The following code can be found at theend of a typical Sphinx configuration file. Complete it to your needds:
# Example configuration for intersphinx: refer to the Python standard library.intersphinx_mapping = {'http://docs.python.org/': None, }
file-wide metadata
when using the following syntax:
:fieldname: some contents
some special keywords are recognised. For instance, orphan, nocomments, tocdepth.
An example of rendering is the toctree of top of this page.
orphan
Sometimes, you have an rst file, that is not included in any rst files (when using include for instance). Yet, there arewarnings. If you want to supprresse the warnings, include this code in the file:
:orphan:
There is also tocdepth and nocomments metadata. See Sphinx homepage.
metainformation
.. sectionauthor:: name <email>Specifies the author of the current section.:
.. sectionauthor:: John Smith <js@python.org>
By default, this markup isn’t reflected in the output in any way, but you can set the configuration valueshow_authors to True to make them produce a paragraph in the output.
32 Chapter 5. Sphinx
XN3.wiki Documentation, Release 0.0.1
contents directives
.. contents::
.. contents:: a title for the contents:depth: 2
•depth indicates the max section depth to be shown in the contents
5.2.11 Useful extensions
In the special file called conf.py, there is a variable called extensions. You can add extension in this variable. Forinstance:
extensions = [-'easydev.copybutton','sphinx.ext.autodoc','sphinx.ext.autosummary','sphinx.ext.coverage','sphinx.ext.graphviz','sphinx.ext.doctest','sphinx.ext.intersphinx','sphinx.ext.todo','sphinx.ext.coverage','sphinx.ext.pngmath','sphinx.ext.ifconfig','matplotlib.sphinxext.only_directives','matplotlib.sphinxext.plot_directive',
]
pngmath: Maths and Equations with LaTeX
The extension to be added is the pngmath from sphinx:
extensions.append('sphinx.ext.pngmath')
In order to include equations or simple Latex code in the text (e.g., 𝛼 ≤ 𝛽 ) use the following code:
:math:`\alpha > \beta`
Warning: The math markup can be used within RST files (to be parsed by Sphinx) but within your python’sdocstring, the slashes need to be escaped ! :math:‘\alpha‘ should therefore be written :math:‘\\alpha‘or put an “r” before the docstring
Note also, that you can easily include more complex mathematical expressions using the math directive:
.. math::
n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k
Here is another:
𝑛offset =
𝑁−1∑︁𝑘=0
𝑠𝑘𝑛𝑘
5.2. Restructured Text (reST) and Sphinx CheatSheet 33
XN3.wiki Documentation, Release 0.0.1
It seems that there is no limitations to LaTeX usage:
𝑠column𝑘 =
𝑘−1∏︁𝑗=0
𝑑𝑗 , 𝑠row𝑘 =
𝑁−1∏︁𝑗=𝑘+1
𝑑𝑗 .
TODO extension
Similarly to the note directive, one can include todo boxes bu it requires the sphinx.ext.todo extension to be added inthe conf.py file by adding two lines of code:
extensions.append('sphinx.ext.todo')todo_include_todos=True
Todo
a todo box
copybutton
When including Python code with the >>> signs, there is a nice extension called copybutton that allows to hide thesigns hence make a copy/paste possible. I put this extension into the package easydev, available on Pypi website. I donot know the origin of this code so sorry if it’s yours. If so, let me know so that I can add the author!copyright.
So, if you add the easydev.extension into the configuration file
extensions.append('easydev.copybutton')jscopybutton_path = easydev.copybutton.get_copybutton_path()
if os.path.isdir('_static')==False:os.mkdir('_static')
import shutilshutil.copy(jscopybutton_path, '_static')
html_static_path = ['_static']
Then, you can add a block code (using the >>> signs) and you should see a clickable set of characters (>>>) in the topright corner to swith on/off the >>> signs:
>>> a=1
Bibliography
34 Chapter 5. Sphinx
CHAPTER 6
Python
6.1 Python cheats
• create virtual python 2.x environment
# virtual env base path# -> change if neededVIRTUALENV_BASE="${HOME}/.vpyes"
# virtual env folder nameVIRTUALENV_NAME='py2ample'
# build virtual env without setup toolsmkdir -pm 755 "${VIRTUALENV_BASE}"virtualenv -p python2 --no-setuptools --no-pip "${VIRTUALENV_BASE}/${VIRTUALENV_NAME}"
# activate new virtual envsource "${VIRTUALENV_BASE}/${VIRTUALENV_NAME}/bin/activate"
# install current setup tools on the fly# -> updated urls find you under https://pypi.python.org/pypi/setuptools# with curlcurl 'https://bootstrap.pypa.io/ez_setup.py' -o - |python# or with wgetwget 'https://bootstrap.pypa.io/ez_setup.py' -O - |python
# install current pipeasy_install pip
35
XN3.wiki Documentation, Release 0.0.1
36 Chapter 6. Python
CHAPTER 7
Sphinx
37
XN3.wiki Documentation, Release 0.0.1
38 Chapter 7. Sphinx
CHAPTER 8
Vim
8.1 Vim cheats
• duplicate current line
:t.
39
XN3.wiki Documentation, Release 0.0.1
40 Chapter 8. Vim
Bibliography
[CIT2002] A citation (as often used in journals).
41
XN3.wiki Documentation, Release 0.0.1
42 Bibliography
Python Module Index
ssample (Unix, Windows), 27
43
XN3.wiki Documentation, Release 0.0.1
44 Python Module Index
Index
Aapical, 30
Ccontents (directive), 33
Hhlist (directive), 30
Ssample (module), 27sectionauthor (directive), 32square() (in module sample), 26
45
top related