User Guide
Version v3.3.1

Style Guidelines

This document provides the style guide for Alyvix with examples of more advanced features and their corresponding RST structures, with at least one example of every supported RST feature.

Paragraphs should not have more than four sentences. Text lines should not be longer than 100 characters except when:

  • A bulleted line is just over 100 characters (e.g., 105)

  • There is a very long sequence with no spaces like a web link

  • There is copied external data like a code block

See additional Sphinx roles not listed below.

Section and Subsection Headers

Titles should have English formatting:

  • Capitalize everything except prepositions

  • Should not be more than one line onscreen at widest setting

To improve readability, there should be three blank lines between sections/subsections. Section headers should have the character sequence both above and below the title text. The characters are (in order): # * = -

Reference anchors above each section title should grow from left to right as nesting depth increases. Because they can be easily broken, they should be changed as infrequently as possible. See here for linking to them. They look like this:

[Optional] section reference
.. _style_sections:

You can use ----- (four or more hyphens) to create a horizontal rule:


You can also add a line of blank space (like a <br />) with a pipe character with a blank line both above and below. Use this sparingly, though, since vertical space should really be created with CSS.


Bulleted and Enumerated Lists, HList and Columns

Bulleted lists should:

  • Always begin with a capital letter and start with the same syntactic type

  • Have the same ending punctuation (either all with . or none)

  • Have the same style, e.g. all newspaper headlines vs. all with complete sentences

  • You can also have multi-line bullet points:

    With indented text and images

    _images/alyvix_logo_399x333.png

    And with non-indented text or images

    _images/alyvix_logo_399x333.png

There are also enumerated lists:

  1. Just like bulleted lists

  2. But start them with #.

    1. Subpoints are just like for bulleted lists

    2. But they are numbered

  3. You can start with a number other than 1 by using its number (4.) instead of the pound sign (#.), but it will affect the very first number at top even if put in a subpoint

The Alyvix custom.css files also supports three alternate enumerated list styles: bignums, bignums-xl (with the onelinelist CSS class option) and bignums-xxl:

  1. bignums creates white numbers in black circles

  2. Can be used together with interface screenshots

This is defined as follows:

.. rst-class:: bignums

#. ``bignums`` creates white numbers in black circles
#. Can be used together with interface screenshots

The other two are defined similarly, and have this appearance:

  1. bignums-xl creates black numbers in grey/white rounded rectangles with a thick border

  2. Useful for overviews of very complex elements

  1. bignums-xxl creates larger numbers and adds a thick horizontal separator

  2. Very useful for lengthy step-by-step procedures when the item content is extensive


Hlist

A horizontal list (.. hlist::) has a fixed number of columns but is otherwise like a bulleted list.

  • Item #1:  

  • Item #2: runblue

  • Item #3: :warn:

  • Item #4: IF TRUE

  • Item #5

  • Item #6

  • Item #7


Containers -> Columns

You can also create a true text column format by combining the .. container:: role with the appropriate CSS. (HTML5 column mode is also possible, but content automatically flows from the bottom of one column to the top of the other.)

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

You may need to manually align the amount of content in each column as sometimes a subsequent paragraph not in column format will be used to fill out the bottom of the right column.

.. container:: twocol

   .. container:: leftside-col

      Text in the left side column

   .. container:: rightside-col

      Text in the right side column

A column-styled set of menu tiles (icons/images + text) can be made by using a table with no borders.

Line Breaks and Vertical Space

Write lines with a pipe character and
a space on the left side of the text to
create text with a break in the middle.
| Write lines with a ``pipe`` character and
| a space on the left side of the text to
| create text with a break in the middle.

You can also make some empty vertical space just using the pipe character by itself.

|

Code Blocks and File Includes

A code block takes the language for the style and keywords, an optional caption that will go in italics above the block, and an optional link reference. Sphinx then places the text in a preformatted HTML block, and uses the Pygment lexer to highlight the text with color according to the language.

The simplest code block just has two colons at the end of one paragraph followed by an indented paragraph (with a blank line separating them). It keeps the code block aligned to the left of the page:

Simple code blocks only have the default options.

Which looks like this in the .rst file:

aligned to the left of the page::

   Simple code blocks only have the default options.

As soon as you return to the previous indentation level, the code block (or preformatted section) will end. If you want more options, you can use the code-block directive:

How to create a code block with options
.. code-block:: <language>
   :caption: How to create a code block with options
   :class: short-code-block
   :name: _style_code_block_example

   This is the content of the code block.
   Sometimes it might even be actual code.

When code blocks are used for syntax highlighting, simply put the Pygment code for the programming language to the right of the directive. Note that Pygment will first check that the syntax is valid before adding highlighting! Bad syntax means the code block appears without highlighting. The console output will then show something like WARNING: Could not lex literal_block as "json".

You can see a complete list of languages recognized by Pygment.

Here’s an example for JSON:

{ "maps": {
     "map-name":  { } },
  "objects": {
     "<test-case-object-name>":  { } },
  "script": {
     "case":  [ ],
     "sections":  { } }
}
.. code-block:: json
   :class: tiny-code-block
   :emphasize-lines: 4

   { "maps": {
        "map-name":  { } },
     "objects": {
        "<test-case-object-name>":  { } },
     "script": {
        "case":  [ ],
        "sections":  { } }
   }

The clipboard copy icon is set by default on all code blocks. To remove it in cases where it doesn’t make sense, add the following class:

.. code-block::
   :class: nocopy

   Don't put a clipboard copy icon in this code block.

In custom.css there are classes available such as medium-code-block, short-code-block and tiny-code-block that will narrow the block at preset proportions (85%, 70% and 50%).

Instead of pasting code into the .rst file, you can also include an entire external file like this:

Importing the content of the file includes.c
.. literalinclude:: includes.c
   :language: c
   :linenos:

Note that you can also include a diff of two files by adding the option :diff: includes.c.orig.

Finally, consider the following for directory structures:

.
├─── composer.json
└─── Documentation
     ├─── Index.rst
     ├─── Settings.cfg
     └─── ...

Text Properties with Custom Roles

You can create a custom role and map it to a custom CSS class in _static/css/custom.css, allowing you to change font color and other properties for selected text within a paragraph. For example, you can add the following CSS to get a large, fixed green font inheriting other Bootstrap CSS features:

.redbold {
    color: red;
    font-weight: bold;
    font-variant: small-caps;
    text-decoration: underline;
 }

At the top of each page where you need this (there is no way to do this globally without changing or customizing the main RTD template itself), add a new Role that is tied to the new CSS class (it can go anywhere in the .rst file):

.. role:: warn
   :class: redbold

You will then be able to use this new warn role within a paragraph as follows:

This is some text where we need to say :warn:`Don't` do something!
:hint:`(You can also make a hint with :hint:)`

Which looks like this when you write it out: “This is some text where we need to say Don’t do something!” (You can also make a hint with :hint:)

Note that you can assign multiple classes when declaring the role:: directive, and you can also do it with the rst-class:: directive. Care should be taken as the ordering will affect which CSS properties are utilized and which are overwritten.

.. rst-class:: bignums-xl
   :class: redbold bluebutton

.. rst-class:: redbold bluebutton bignums-xl

Tables

There are simple, complex, CSV and list-type tables. You can span multiple columns (even in simple tables) and indicate a blank cell either with a comment ( .. ) or a backslash ( \ ).

Here is a simple table:

Name

Syntax

Format

Italics

*

Italics

Bold

**

Bold

Mono

``

Monospace

Subscript

a\ :subscript:`sub`

asub

Superscript

b\ :superscript:`super`

bsuper

Mixed

*Ita*\ **Bol**\ ``Lit``\s

ItaBolLits

Math

:math:`…`

\(\\\sum_{k=0}^{N-1} s_k\)

Roles defined by Sphinx and DocUtils

GUI

:guilabel:`File > Settings`

File > Settings

Keys

:kbd:`ctrl` + `:kbd:`s`

ctrl + s

File

:file:`/etc/passwd`

/etc/passwd

Roles defined by in-page directives (/sphinx-roles.txt) and custom.css

Warn

:warn:`Warn`

Warn

Hint

:hint:`Hint`

Hint

SmallCaps

:caps:`CamelCase`

CamelCase

This is built as follows:

===========  ======================================  =========
Name         Syntax                                  Format
-----------  --------------------------------------  ---------
Italics      \*                                      *Italics*
Bold         \**                                     **Bold**
Mono         \``                                     ``Monospace``
Subscript    a\\ :subscript:\`sub\`                  a\ :subscript:`sub`
Superscript  b\\ :superscript:\`super\`              b\ :superscript:`super`
Mixed        \*Ita\*\\ \*\*Bol\*\*\\ \`\`Lit\`\`\\s  *Ita*\ **Bol**\ ``Lit``\s
Math         \:math:\`...\`                          :math:`\\\sum_{k=0}^{N-1} s_k`
-----------  --------------------------------------  ---------
:caps:`Roles defined by Sphinx and DocUtils`
--------------------------------------------------------------
GUI          \:guilabel\:\`File > Settings\`         :guilabel:`File > Settings`
Keys         \:kbd\:\`ctrl\` + `\:kbd\:\`s\`         :kbd:`ctrl` + :kbd:`s`
File         \:file\:\`/etc/passwd\`                 :file:`/etc/passwd`
-----------  --------------------------------------  ---------
:caps:`Roles defined by in-page directives (`:file:`/sphinx-roles.txt`:caps:`) and` :file:`custom.css`
--------------------------------------------------------------
Warn         \:warn\:\`Warn\`                        :warn:`Warn`
Hint         \:hint\:\`Hint\`                        :hint:`Hint`
SmallCaps    \:caps\:\`CamelCase`                    :caps:`CamelCase`
===========  ======================================  =========

Note: sphinx-build will complain if there is text in between the defined columns (but not if it sticks out the right hand side).

And here is a complex table:

Header row, column 1 (header rows optional)

Header 2

Header 3

Header 4

body row 1, column 1

column 2

column 3

column 4

body row 2

…Spanning text…

Built like so:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+------------------------+------------+----------+----------+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...Spanning text... |
+------------------------+------------+----------+----------+

Column widths and other modifiers can be specified if you use the full table environment. Note however that themes based on bootstrap don’t currently have 100% CSS compatibility with Sphinx. The widths (percentage widths of the column tables) parameter works, but for alignment use a special CSS class.

Color

Description

Green

Leaves on the trees


.. table::
   :class: table-justify-right
   :widths: 20 40

   +-------------+---------------------+
   | Color       | Description         |
   +-------------+---------------------+
   | Green       | Leaves on the trees |
   +-------------+---------------------+

Here’s an example of apparent columns via a table adding a class that removes borders:

Item A1

Item B1

Item C1

Item A2

Item B2

Item C2

Item A3

Item B3

Item C3

.. table::
   :widths: 33 33 33
   :class: table-empty-no-borders

   +---------+---------+---------+
   | Item A1 | Item B1 | Item C1 |
   +---------+---------+---------+
   | Item A2 | Item B2 | Item C2 |
   +---------+---------+---------+
   | Item A3 | Item B3 | Item C3 |
   +---------+---------+---------+

And the same table with the table-body-no-borders class applied:

Item A1

Item B1

Item C1

Item A2

Item B2

Item C2

Item A3

Item B3

Item C3

Item A4

Item B4

Item C4


Images, Figures and Icons

There are a number of options for images, such as resizing and placement. Using the :align: keyword will allow text to wrap around the sides; to place an image on the left side without allowing wrapping on the right, just leave out the parameter altogether. Clicking on the image in the browser will load the image by itself into the browser window.

Bootstrap for Sphinx doesn’t support every standard Sphinx/ReST parameter. A case in point is alignment: use the classes “mx-auto d-block” as described in the Bootstrap doc to center rather than the :align: keyword.

This is alternate text.

This is built as follows:

.. image:: pictures/alyvix_logo_399x333.png
   :class: mx-auto d-block
   :width: 200px
   :height: 100px
   :alt: This is alternate text.

You can add shadows and other effects by adding a specific CSS class to custom.css as follows (note that figures and images have different options):

.. image:: pictures/alyvix_logo_399x333.png
   :class: image-boxshadow

You can also make a more structured figure. It assumes you want an image at the top with the basic options above. A paragraph at the same indentation level as the options will be treated as a caption, and any additional indented structures will be treated as a figure legend.

You can set an empty caption by using the standard .. paragraph comment. but can also put an entire (indented) RST structure within the figure space. You can add the class :class: outline to the figure declaration and custom.css will add a thin-lined box around the image (but not the caption):

This is alternate text.

Fig. 1: The indented structure becomes like a caption.

.. figure:: pictures/alyvix_logo_399x333.png
   :class: outline mx-auto d-block
   :scale: 40 %
   :alt: This is alternate text.
   :figwidth: 50 %
   :target: http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure

   Fig. 1:  The indented structure becomes like a caption.

When using the :target: parameter, internal paths should have the following format so that they work both on a local copy and on the hosted site:

:target: ../_images/<filename>.png

Some support for figure numbering is available: Add the line numfig = True to conf.py and then before the figure add the line .. _label_fig1:, and then the reference :refnum:`label_fig1 where needed in the text. Unfortunately for now, it inserts an HTML link along with the number (see also numfig_format and numfig_secnum_depth), and the numbering starts over again within each subsection, and these aren’t numbered.

(Automatic section numbering is also possible with an extension to Sphinx: http://docutils.sourceforge.net/docs/ref/rst/directives.html#automatic-section-numbering)

For freely available Font Awesome 5.x icons, use the far directive:

With text, or use the | by itself for just the icon

Just append fa- to the name of the Font Awesome icon you want (or use the notation in the sphinx-panels extension at the bottom of this page):

.. rst-class:: far fa-med fa-check-circle

   With text, or use the ``|`` by itself for just
   the icon (it's always placed as ``::before``)

Note that only free icons are available, and that there is a difference between FA version 4 and FA version 5 (older Sphinx themes use 4.x, newer ones like sphinx-bootstrap-theme use version 5).

A single inline icon is also possible by adding fa-small as long as it’s at the start of a sentence/bullet (see _static/css/custom.css for other sizes):

I’m a play-circle Font Awesome icon

If you want the icon in the middle of the text instead of at the beginning, define a custom alias in ./sphinx-roles.rst, although this requires raw HTML (see the warning below).

Some Font Awesome icons have predefined roles:

Icon

Usage

Appearance

Download

:download:`file.txt`

file.txt

Note

On compilation, Sphinx will check that the file actually exists at the path specified.

Don’t use RAW HTML to do it (unless required to circumvent the above to restrictions, but even then think hard about it due to the security concerns of raw HTML):

.. raw:: html

   <i class="fa fa-inbox"></i>

Here’s a naughty example of using a role directive to pass through raw HTML to create an airplane icon.

Info Boxes, Pull Quotes and Rubrics

Info boxes let you create text for a particular purpose, that quickly catches the eye.

Note

This is a note style of info box. It can contain bulleted lists and other formatting.

Warning

The warning style of info box has different colors.

The other box types are: admonition, attention, caution, danger, error, hint, important, seealso and tip.

The custom.css file allows you to pass a class name to make it less than full width:

Danger

A short Danger box

.. danger::
   :class: short-admonition

   A short **Danger** box

The right-short-admonition class does the same but aligns the shortened box to the right side of the window.

Hint

A right-aligned, short Hint box

.. danger::
   :class: right-short-admonition

   A right-aligned, short **Hint** box

Epigraphs and Pull Quotes

Additional styles like epigraph and pull-quote can be tied to specific CSS classes with those names.

A test epigraph

“Followed by a test pull-quote„

.. pull-quote::

   “Followed by a test pull-quote„

Rubric Titles

A rubric is for when you need a section with title that shouldn’t be included in the index (e.g., its content is too small). Rubrum is the Latin word for red, as was often used in medieval manuscripts as the color for titles.

How you can create a rubric
.. rubric:: Rubric Titles

A **rubric** is for when you need a section with title that shouldn't be
included in the index (e.g., its content is too small).  *Rubrum* is the
Latin word for *red*, as was often used in medieval manuscripts as the
color for titles.

Comments

Comments are not visible in the rendered document. See? No comment visible here:

The above comment appears this way in the source file:

.. This is a comment that will not be included.

You can even comment entire sections by indenting appropriately under a comment.

Using Raw HTML

If necessary, straight HTML can be inserted into the guide. It’s not needed for block elements, since they can have custom classes and thus custom CSS. Sometimes it may be necessary for third party plugins (video, twitter, instance with third party Note there are several problems, though:

  • It’s a potential security hole

  • It reduces portability

  • You can’t put aliases (macro substitution) inside it

  • For goodness sake, don’t put custom CSS in it, just link it to a custom CSS class in the Sphinx template

Here are some examples:

  • Press the Enter key.
  • Network
  • Add
  • Add Map
  • Allow viewing of all logs
  • Test + Text pqj

And don’t forget that you can alias and reuse all of these:

Like pressing the Enter key many times: Enter Enter Enter

.. |enterkey| raw:: html

   <kbd style="background-color: rgba(62,155,161); color: #fff; font-weight: 400; padding-left: 6px; padding-right: 6px; border-style: none; border-radius: 7px;">Enter</kbd>

Sphinx and Optional Sphinx Extensions

The required Python modules (we recommend you install them via pip) for building the documentation are:

  • sphinx

  • sphinx_rtd_theme

  • sphinx-copybutton

We typically build the user guide with the following command. You will need to change the executable and source/build directory names according to your environment.

> C:\Python37\python.exe -m sphinx.__main__ -E -a -b html C:\projects\alyvix_doc C:\projects\alyvix_doc\_build

The extensions below can be installed as desired. Only the copy/accordion button extension is included by default in this repository.

Dynamic Copy and Accordion Buttons

This extension to Sphinx’s sphinx-copybutton extension improves the usability of the copy-to-clipboard function for code blocks and adds accordion buttons. To use it:

  • Install the extension with pip install sphinx-copybutton

  • Add 'sphinx_copybutton' to the extension list in Sphinx’s conf.py

Then modify the file Python37/Lib/site-packages/sphinx_copybutton/static/copybutton.js_t to allow disabling the copy button for a code block by adding :class: nocopy to the RST directive, and to filter out command prompts when copying from code blocks. In that file you’ll need to modify these parts as shown below:

  • Change the English messages at the top

  • Replace the addCopyButtonToCodeCells function

  • Replace the copyTargetText function

  • Add and call the addButtonToAccordionCells function

const messages = {
  'en': {
    'copy': 'Copy to clipboard',
    'copy_to_clipboard': 'Copy to clipboard',
    'copy_success': 'Copied',
    'copy_failure': 'Failed to copy',
  },
const addCopyButtonToCodeCells = () => {
  // If ClipboardJS hasn't loaded, wait a bit and try again. This
  // happens because we load ClipboardJS asynchronously.
  if (window.ClipboardJS === undefined) {
    setTimeout(addCopyButtonToCodeCells, 250)
    return
  }

  // Add copybuttons to all of our code cells
  const codeCells = document.querySelectorAll('{{ copybutton_selector }}')
  codeCells.forEach((codeCell, index) => {
    const id = codeCellId(index)
    codeCell.setAttribute('id', id)
    const pre_bg = getComputedStyle(codeCell).backgroundColor;

    const clipboardButton = id =>
    `<a class="copybtn o-tooltip--left" style="background-color: ${pre_bg}" data-tooltip="${messages[locale]['copy']}" data-clipboard-target="#${id}">
      <img src="${DOCUMENTATION_OPTIONS.URL_ROOT}_static/{{ copybutton_image_path }}" alt="${messages[locale]['copy_to_clipboard']}">
    </a>`
    grandparent = codeCell.parentElement.parentElement;  // Line added by Charles@WP  ---  Don't add a copy button when the code block doesn't want it
    if ((grandparent.getAttribute('class') == null) || (grandparent.getAttribute('class').search('nocopy') < 0)) {  // Conditional added by Charles@WP
        codeCell.insertAdjacentHTML('afterend', clipboardButton(id))
    }
  })
var copyTargetText = (trigger) => {
  var target = document.querySelector(trigger.attributes['data-clipboard-target'].value);
  var textContent = target.textContent.split('\n');
  if (textContent[0].startsWith('C:\\> ')) { return textContent[0].slice(5); } // Line added by Charles@WP
  if (textContent[0].startsWith('C:\\Alyvix\\testcases> ')) { return textContent[0].slice(21); } // Line added by Charles@WP
  textContent.forEach((line, index) => {
    if (line.startsWith(copybuttonSkipText)) {
      textContent[index] = line.slice(copybuttonSkipText.length)
    }
  });
  return textContent.join('\n');
}

And the accordion-style expand/contract buttons are here as well since they use the same DOM approach as the copy buttons:

const addButtonToAccordionCells = () => {
  // Add accordion buttons to all classes containing the 'accordion' class
  const accordionCells = document.querySelectorAll('button.accordion')
  accordionCells.forEach((accordionCell, index) => {
    accordionCell.parentNode.replaceWith(accordionCell)
    accordionCell.addEventListener("click", function() {
      this.classList.toggle("active");
      var panel = this.nextElementSibling;
      if (panel.style.display === "block") { panel.style.display = "none"; }
      else { panel.style.display = "block"; }
    });
  })
}
runWhenDOMLoaded(addButtonToAccordionCells)

Also add the accordion CSS class to the file Python37/Lib/site-packages/sphinx_copybutton/static/copybutton.css:

button.accordion {
    background-color: rgb(41,128,185);
    color: #fff;
    cursor: pointer;
    padding: 7px 14px;
    width: 94%;
    border: none;
    align: center;
    text-align: left;
    outline: none;
    margin-top: 10px;
}

Sphinx Panels

The Sphinx Panels extension adds the following features:

  • Card panels

  • Tabbed panels

  • Button style links that can also serve as links for a whole panel

  • Dropdown boxes that can hide content like FAQ answers

  • Github Octicons and improved FontAwesome support

Badges

Let’s start with the simplest first, badges, a kind of text version of the GitHub repo status badge:

primary secondary

:badge:`primary,badge-alyvix-primary`
:badge:`secondary,badge-secondary badge-pill`

Card Panels

Card panels are containers that use Bootstrap to size and position themselves appropriately (see the linked page above for additional formatting options):

Panel #1

badge1 New!

Panel #2

A link to Alyvix with tooltip

Panel #3

Panel #4

There’s hidden content above me

img-top

Panel #5 with Image at Top

.. panels::

   Panel #1
   ^^^^^^^^

   :badge:`badge1,badge-alyvix-primary`
   :badge:`New!,badge-warning`

   ---

   Panel #2

   A link to :link-badge:`https://www.alyvix.com/,"Alyvix",tooltip=A Tooltip` with tooltip

   ---
   :body: text-center

   Panel #3

   ++++++++++
   * List #3A
   * List #3B

   ---

   Panel #4
   ^^^^^^^^

   .. dropdown:: :fa:`arrow-circle-right` Panel #4 Button

      Hidden content

   There's hidden content above me

   ---

   Panel #5 with Image at Top

   .. dropdown:: Panel #5 Button

      The content below is a *link-button*:

      .. link-button::  https://www.alyvix.com
         :text: www.alyvix.com
         :classes: bluebutton

Tabbed Panels

Tabbed panels (used to show the RST code above) let you overlay multiple content elements in the same space, allowing the user to choose which one to see. You can use the :new-group: parameter after a new tab to start a new set of tabbed panels, :selected: to select a default tab, and :class-label: and :class-content: among other formatting options.

We’ve changed the default blue color in tab panels to match our Alyvix blue, which is done by setting the appropriate variable in panels_css_variables in conf.py.

Text in tab panel #1

.. tabbed:: Tab #1 (Appearance)
   :class-label: smallcaps
   :class-content: redbold

   Text in tab panel #1

Font Icons

Font icons, whether Github’s Octicons or the more traditional Font Awesome icons, are now supported with RST directives, although you will probably need to add CSS to the css/custom.css file:

Octicon (screen-full):           FA (bars):           Octicon (x-circle):    

Octicon (screen-full): |halftab| :opticon:`screen-full,,size=16` |tab|
FA (bars): |halftab| :fa:`bars,fa-small` |tab|
Octicon (x-circle): |halftab| :opticon:`x-circle,text-white bg-danger,size=24`

Note that although they are called Octicons, the sphinx-panel RST role calls them Opticons.


Optional Sphinx Extensions and HTML/CSS

Graphviz

Graphviz has several requirements that must be satisfied before it can be used:

  • Downloaded and installed on the machine running the Sphinx build process

  • Add 'sphinx.ext.graphviz' to the extension list in Sphinx’s conf.py

  • Add an additional build option with the path where GraphViz is installed, e.g.: -D graphviz_dot="C:\Program Files (x86)\Graphviz2.38\bin\dot.exe"

  • As this is a natively supported extension, no pip install command is necessary

Note that the :class: parameter currently doesn’t work, so any additional elements will have to be added in custom.css on the default graphviz class. For styling internal elements like the background color (GraphViz supports RGBA and named colors), you will need to pass those as arguments to GraphViz itself. Remember that GraphViz passes back a dynamically generated png file like _images/graphviz-3834087134ab82.png, so you can’t change anything internally if it’s not in the specification.

.. graphviz::
   :alt: alt-text
   :align: center
   :caption: graphviz-caption
   :class: gv-background

   digraph foo {
      bgcolor="#fcfcfc00"
      "bar" -> "baz";
   }

.graphviz {
    padding: 5px;
}

Embedded YouTube Videos

Add a YouTube video specifying the whole URL or just the code. We have tested this with no problems, but currently have decided not to embed videos, so we use thumbnails to external links instead.

  • Install in Python with pip install sphinxcontrib.youtube

  • Add 'sphinxcontrib.youtube' to the extension list in Sphinx’s conf.py

Usage examples:

.. youtube:: http://www.youtube.com/watch?v=Qef7ExMoPz8

.. topic:: An Embedded Video

   .. youtube:: Qef7ExMoPz8

Note that we currently modify the default files to change the CSS and use the proper HTML: Python37/Lib/site-packages/sphinxcontrib/youtube/youtube.py

def visit(self, node):

    video_id = get_video_id(node.url)

    url = u'//www.youtube.com/embed/{0}?feature=player_detailpage'.format(video_id)

    tag = u'''<div class="section" id="youtube-videos"><iframe src="https://www.youtube.com/embed/{0}" style="border: 0; height: 345px; width: 560px">
  </iframe></div>'''.format(video_id)

    self.body.append(tag)

PDF Conversion

The following steps are required:

  • Install via pip install rst2pdf

  • Add 'rst2pdf.pdfbuilder' to the extension list in Sphinx’s conf.py

  • Add a new build command with the path where GraphViz is installed, e.g.: -E -a -b pdf C:\projects\alyvix_doc C:\projects\alyvix_doc\_build

The result will be a file called Python.pdf in the _build directory. The quality isn’t that great, but it’s complete (including the todo’s even when they are turned off).

Note that as of February 2020, Rinoh (pip install rinohtype) is not working in Python 3.7.

Potential HTML and CSS Integrations

Scroll-to-Top Button

.. raw:: html

   <button onclick="topFunction()" id="topButton" title="Go to top">Top</button>

Text Superimposed on Images

Let’s create a background image, and then overlay some text on top of it:


Here is some Text


Some more text


Icons!


.. raw:: html

   <div class="demo-image">
     <img src="_images/alyvix_logo_399x333.png" style="width:50%; height:50%;"/>
     <div class="demo-text" height="100%">
       <br />
       <h1>Here is some Text</h1><br />
       <p><b>Some more text</b></p><br />
       <p><b>Icons! <i class="fa fa-inbox"></i></b></p><br />
     </div>
   </div>

Overlay on Darkened Background

Button

.. raw:: html

   <div id="overlay">Some Text</div>

Image “Cards”

card1

Alyvix #1

Software Architect

card2

Alyvix #2

Video Producer

.. raw:: html

   <div id="overlay">Some Text</div>