Skip to content

FreeWillyB/nems-docs

 
 

Repository files navigation

nems-docs

Documentation for NEMS Linux.

You can review the live version of this repository at https://docs.nemslinux.com/

Documentation Status

Helpful Resources

I'm actually new to Restructured Text, though I see similarities to some of the Discord markdown. So having some resources to help find quick syntax forumulae can be helpful. Here are some that I've turned to for help:

Guidelines

As I would like the documentation to have a consistent look throughout, please follow these guidelines for your edits. You are also welcome to add to these guidelines if you have a suggestion for certain layouts.

Layout

Images

When embedding an image, please place the image in /img and use the following format:

.. figure:: ../../img/relative_filename.jpg
  :width: 600
  :align: center
  :alt: Alt text describing image goes here

  Caption goes here

When adding an image inline with the text place the image in /img and use the following format

.. |image| image:: ../../img/image.png
   :height: 2em

Image files need to be JPG or PNG. Sadly, ReadTheDocs doesn't appear to support WebP (they don't show up).

Embed YouTube Video

To embed a YouTube video, go to YouTube video page and click on Share below the video and then select Embed. Copy the entire HTML tag with the <iframe> tag. In the rst file, type in

.. raw:: html

   <iframe> code here

Ensure the iframe code lines up directly below the "r" in raw

For pictorial instructions go here: https://techwritingmatters.com/documenting-with-sphinx-tutorial-part-3-writing#6_Embedding_a_YouTube_video

Inline Text Variation

Restructured Text can process inline text variations, but as ReST requires a space on either side, escaping is required.

To achieve restructured text you would type it as follows: **r**\ estructured **t**\ ext

I've also included some custom css classes to allow doing things that are normally not possible with ReST, such as bold and italic at the same time.

Just add this to the first line of your .rst file: .. include:: ../global.rst

Then, you can do something like this: **r**\ :bolditalic:`estructured` **t**\ :bolditalic:`ext`

Other Custom Classes

:underline:`text`

Note that \ followed by a space will not actually render a space in the output.

Step-By-Step Instructions

When including step-by-step instructions, please use number lists at the top level and second level in such a way that future readers may refer to the instruction as, for example, 2.3 (the 2nd list, 3rd item). If you desire to include images within the steps, you will need to pay particular attention to how this impacts your automated numbering (#.) and may need to switch to static numbering (1., 2., etc).

1. Introduction to the section.
  #. This would be step 1 (referred to as 1.1)
  #. This would be step 2 (referred to as 1.2)
  #. This would be step 3 (referred to as 1.3)
2. Introduction to the next section.
  #. Step 1 (referred to as 2.1)
  #. Step 2 (referred to as 2.2)
  #. Step 3 (referred to as 2.3)

If editing existing step-by-step instructions, please be particularly mindful that if the numbering changes, any previous post in the community referencing the step will now be broken. Please try to avoid such a situation if possible.

Blocks

Code Block

.. code-block:: console

    Here is some code.
    Here is the second line of code.
    If this is the final line of code, simply have a carriage return following it.

Tip Block

.. Tip:: Text for the tip is here

Warning Block

.. Warning:: Text for the tip is here

Exercise Block

.. admonition:: Exercise
  :class: note
  
  Text for the exercise is here

About

Documentation for NEMS Linux

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 82.1%
  • Makefile 9.9%
  • CSS 5.8%
  • JavaScript 2.2%