Creating new pages

The first step on adding new content is to understand the Documentation structure. Then, proceed with Adding content.

Documentation structure

This repository hosts any type of content that is not version controlled with a particular source code, or in other words, “don’t deserve their own repository”.

Due to this, there are multiple topics, for example, there is information from Linux drivers to Evaluation boards user guides.

As an analogy, if this documentation were a encyclopedia, each topic would be a volume.

To create each “volume”, two toctrees replicate the structure of the context top level.

For example, while in docs/index.rst#L19-L25 we have:

.. toctree::
   :caption: Linux Kernel & Software
   :maxdepth: 2

   linux/kuiper/index
   linux/drivers/index
   linux/kernel/index

At the specific context toctree (docs/linux/index.rst#L6-L10) we have:

.. toctree::

   kuiper/index
   drivers/index
   kernel/index

Use case for the structure

This structure enables to concatenate other documentations (“volumes”) to this one, allowing to generate an aggregated monolithic output, for example.

Suppose we have a repository called my-repo with the following toctree:

.. toctree::
   :glob:

   */index

Tip

Notice the usage of the :glob: options. It is particular useful to avoid merge conflict scenarios.

To add to this doc, we only need to append to docs/index.rst as:

.. toctree::
   :glob:

   my-repo/*/index

And copy my-repo/docs as documentation/docs/my-repo (mostly).

Adding content

The documentation is highly hierarchical and contextual, that means a page about “Peeling Blue Bananas” should be located at fruits/banana/blue/peeling.rst and not eval/tutorial-peeling_blue_bananas.rst.

The title should also be kept short, since it directly inherits the context from the hierarchical structure, so it’s preferred:

Peeling blue bananas
=====================

Over:

Fruits tutorials: peeling blue bananas
======================================

At the toctree, the title shall be overwritten to reduce the title length on the sidebar further:

Blue bananas
============

.. toctree::

   Peeling <peeling>
   Recipes <recipes>

Tip

Don’t overthink the location of the content, it can be easily moved later. Just try to keep it contextual and hierarchical.

Having that in mind, proceed with creating the directories, toc-entries, and files for your content:

$

cd ~/documentation/docs ; pwd

~/documentation/docs

$

mkdir my_topic

$

# Add "My Topic" to the main index

$

vi index.rst

$

# Create topic/volume index

$

vi my_topic/index.rst

$

# Create more content

$

vi my_topic/page0.rst my_topic/page1.rst

$

# Add/create images

$

cp ~/some-image.svg my_topic/

...

Edit my_topic/index.rst, adding a title and some content.

Build the doc and see the changes:

~/documentation/docs$

make html

Tip

Sphinx only rebuilds modified files, so toctree changes may look like they are not “applying” to the documentation. Just rebuild the whole doc with make clean html if the output is confusing.

Even better than having to run make html at every edit, you can leverage Why was Author Mode renamed to Serve? to have a live-updating instance of the doc, you just need to save the file and the build will be triggered automatically.

Importing from DokuWiki

To import content from dokuwiki, a script is available to help on this task: DokuWiki to Sphinx (bash.sh).

It requires you have pandoc and sed installed:

sudo apt install pandoc sed

It will try its best to reduce the amount of manual work necessary, still, please review the content carefully.

For images, ensure to click on the image on wiki.analog.com to ensure you download the original and not the compressed image.

Always prioritize vector images (.svg).

Finally, content yet not imported, keep/use the Dokuwiki role. And for deprecated content, add the qualifier +deprecated, for example:

:dokuwiki+deprecated:`Old content <resources/old/content>`

The reason for this is that with this differentiation we can easily track yet to import pages and deprecated content with:

~/documentation/docs$

grep --exclude-dir=_build -rnw :dokuwiki:

software/libiio/internals.rst:58:like :dokuwiki:`GNU Radio ...
software/libiio/index.rst:270::dokuwiki:`here <resources/t ...
...

~/documentation/docs$

grep --exclude-dir=_build -rnw :dokuwiki+deprecated:

software/libiio/index.rst:54:* :dokuwiki+deprecated:`Beac ...
...