For this you will need to know somereStructuredText. There is no going around this. reStructuredTextfiles have rst extensions. However, these are simple text files. Use any text editor you like. Finding a text editor that offers syntax highlighting forreStructuredTextwas quite a challenge at the time of writing this tutorial. In my experience,Intypeis a solid option on Windows, although there is still place for improvement.
Adding your source code to a table of content is important for multiple reasons. First and foremost this will allow for the user base to find your tutorial from our websites tutorial table of content. Secondly, if you omit this Sphinx will throw a warning that your tutorial file isn’t part of any TOC tree entry. And there is nothing more than the developer team hates than an ever increasing warning/error list for their builds. Sphinx also uses this to build up the previous-back-up buttons on the website. Finally, omitting this step will lead to that your tutorial will not be added to the PDF version of the tutorials.
Navigate to theopencv/doc/tutorials/section/table_of_content_section folder (where the section is the module to which you’re adding the tutorial). Open the table_of_content_section file. Now this may have two forms.
If no prior tutorials are present in this section that there is a template message about this and has the following form:
.. _Table-Of-Content-Section:
The first line is a reference to the section title in the reST system. The section title will be a link and you may refer to it via the:ref:directive. The include directive imports the template text from the definitions directories noContent.rst file. Sphinx does not creates the PDF from scratch. It does this by first creating a latex file. Then creates the PDF from the latex file. With the raw directive you can directly add to this output commands. Its unique argument is for what kind of output to add the content of the directive. For the PDFs it may happen that multiple sections will overlap on a single page. To avoid this at the end of the TOC we add a pagebreak latex command, that hints to the LATEX system that the next line should be on a new page.
If you have one of this, try to transform it to the following form:
.. _Table-Of-Content-Section:
You will learn how to store images in the memory and how to print out their content to the console.
=============== =====================================================
.. |MatBasicIma| image:: images/matTheBasicImageStructure.jpg
:height: 90pt
../mat - the basic image container/mat - the basic image container
If this is already present just add a new section of the content between the include and the raw directives (excluding those lines). Here you’ll see a new include directive. This should be present only once in a TOC tree and the reST file contains the definitions of all the authors contributing to the OpenCV tutorials. We are a multicultural community and some of our name may contain some funky characters. However, reST only supports ANSI characters. Luckily we can specify Unicode characters with the unicode directive. Doing this for all of your tutorials is a troublesome procedure.
Therefore, the tocDefinitions file contains the definition of your author name. Add it here once and afterwards just use the replace construction. For example here’s the definition for my name:
.. |Author_BernatG| unicode:: Bern U+00E1 t U+0020 G U+00E1 bor
The|Author_BernatG|is the text definitions alias. I can use later this to add the definition, like I’ve done in the TOCs Author part. After the:: and a space you start the definition. If you want to add an UNICODE character (non-ASCI) leave an empty space and specify it in the format U+(UNICODE code). To find the UNICODE code of a character I recommend using theFileFormatwebsites service. Spaces are trimmed from the definition, therefore we add a space by its UNICODE character (U+0020). Until the raw directive what you can see is a TOC tree entry. Here’s how a TOC entry will look like:
.. tabularcolumns:: m{100pt} m{300pt}
You will learn how to store images in the memory and how to print out their content to the console.
=============== ======================================================
.. |MatBasicIma| image:: images/matTheBasicImageStructure.jpg :height: 90pt
:width: 90pt
As you can see we have an image to the left and a description box to the right. To create two boxes we use a table with two columns and a single row. In the left column is the image and in the right one the description. However, the image directive is way too long to fit in a column. Therefore, we need to use the substitution definition system. We add this definition after the TOC tree. All images for the TOC tree are to be put in the images folder near itsreStructuredText file. We use the point measurement system because we are also creating PDFs. PDFs are printable documents, where there is no such thing that pixels (px), just points (pt). And while generally space is no problem for web pages (we have monitors with huge resolutions) the size of the paper (A4 or letter) is constant and will be for a long time in the future. Therefore, size constrains come in play more like for the PDF, than the generated HTML code.
Now your images should be as small as possible, while still offering the intended information for the user. Remember that the tutorial will become part of the OpenCV source code. If you add large images (that manifest in form of large image size) it will just increase the size of the repository pointlessly. If someone wants to download it later, its download time will be that much longer. Not to mention the larger PDF size for the tutorials and the longer load time for the web pages. In terms of pixels a TOC image should not be larger than 120 X 120 pixels. Resize your images if they are larger!
Note: If you add a larger image and specify a smaller image size, Sphinx will not resize that. At build time will
1.17. How to write a tutorial for OpenCV 129
add the full size image and the resize will be done by your browser after the image is loaded. A 120 X 120 image is somewhere below 10KB. If you add a 110KB image, you have just pointlessly added a 100KB extra data to transfer over the internet for every user!
Generally speaking you shouldn’t need to specify your images size (excluding the TOC entries). If no such is found Sphinxwill use the size of the image itself (so no resize occurs). Then again if for some reason you decide to specify a size that should be the width of the image rather than its height. The reason for this again goes back to the PDFs. On a PDF page the height is larger than the width. In the PDF the images will not be resized. If you specify a size that does not fit in the page, then what does not fits in will be cut off. When creating your images for your tutorial you should try to keep the image widths below 500 pixels, and calculate with around 400 point page width when specifying image widths.
The image format depends on the content of the image. If you have some complex scene (many random like colors) then use jpg. Otherwise, prefer using png. They are even some tools out there that optimize the size of PNG images, such asPNGGauntlet. Use them to make your images as small as possible in size. Now on the right side column of the table we add the information about the tutorial:
• In the first line it is the title of the tutorial. However, there is no need to specify it explicitly. We use the reference system. We’ll start up our tutorial with a reference specification, just like in case of this TOC entry with its ‘‘ ..
_Table-Of-Content-Section:‘‘ . If after this you have a title (pointed out by the following line of -), then Sphinx will replace the:ref:‘Table-Of-Content-Section‘directive with the tile of the section in reference form (creates a link in web page). Here’s how the definition looks in my case:
.. _matTheBasicImageContainer:
Mat - The Basic Image Container
*******************************
Note, that according to thereStructuredTextrules the * should be as long as your title.
• Compatibility. What version of OpenCV is required to run your sample code.
• Author. Use the substitution markup ofreStructuredText.
• A short sentence describing the essence of your tutorial.
Now before each TOC entry you need to add the three lines of:
+
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
The plus sign (+) is to enumerate tutorials by using bullet points. So for every TOC entry we have a corresponding bullet point represented by the +. Sphinx is highly indenting sensitive. Indentation is used to express from which point until to which point does a construction last. Un-indentation means end of that construction. So to keep all the bullet points to the same group the following TOC entries (until the next +) should be indented by two spaces.
Here, I should also mention that always prefer using spaces instead of tabs. Working with only spaces makes possible that if we both use monotype fonts we will see the same thing. Tab size is text editor dependent and as should be avoided. Sphinx translates all tabs into 8 spaces before interpreting it.
It turns out that the automatic formatting of both the HTML and PDF(LATEX) system messes up our tables. Therefore, we need to help them out a little. For the PDF generation we add the.. tabularcolumns:: m{100pt} m{300pt}
directive. This means that the first column should be 100 points wide and middle aligned. For the HTML look we sim-ply name the following table of a toctableopencv class type. Then, we can modify the look of the table by modifying the CSS of our web page. The CSS definitions go into theopencv/doc/_themes/blue/static/default.css_t file.
.toctableopencv {
width: 100% ;
table-layout: fixed;
However, you should not need to modify this. Just add these three lines (plus keep the two space indentation) for all TOC entries you add. At the end of the TOC file you’ll find:
.. raw:: latex
\pagebreak .. toctree::
:hidden:
../mat - the basic image container/mat - the basic image container
The page break entry comes for separating sections and should be only one in a TOC treereStructuredTextfile. Finally, at the end of the TOC tree we need to add our tutorial to the Sphinx TOC tree system. Sphinx will generate from this the previous-next-up information for the HTML file and add items to the PDF according to the order here. By default this TOC tree directive generates a simple table of contents. However, we already created a fancy looking one so we no longer need this basic one. Therefore, we add the hidden option to do not show it.
The path is of a relative type. We step back in the file system and then go into the mat - the basic image containerdirectory for themat - the basic image container.rstfile. Putting out the rst extension for the file is optional.