Browse Source

Added cheatsheet

master
neauoire 1 day ago
parent
commit
206a0f37ac
4 changed files with 154 additions and 2 deletions
  1. +2
    -2
      README.md
  2. +1
    -0
      TODO.md
  3. +150
    -0
      src/source/cheatsheet.rst
  4. +1
    -0
      src/source/index.rst

+ 2
- 2
README.md View File

@@ -16,6 +16,7 @@ Install [Sphinx(https://docs.readthedocs.io/en/stable/intro/getting-started-with
```
sudo pacman -S python
sudo pacman -S python-pip
sudo pacman -S texlive-core # latex support
sudo pip install sphinx
sudo pip install recommonmark # to parse md
```
@@ -32,6 +33,5 @@ firefox build/html/index.html

```
cd src
make latex

make latexpdf
```

+ 1
- 0
TODO.md View File

@@ -64,3 +64,4 @@
- Sinclair Programming: https://k1.spdns.de/Vintage/Sinclair/80/Sinclair%20ZX81/ZX81%20Basic%20Programming.pdf
- https://mntre.com/reform2-handbook/system.html
- https://mntre.com/reform2-ibom/reform2-motherboard/ibom.html
- Font: https://www.brailleinstitute.org/freefont

+ 150
- 0
src/source/cheatsheet.rst View File

@@ -0,0 +1,151 @@
Sphinx cheatsheet

A brief overview of some of the main functions of Sphinx
as used in the aiida documentation. View :ref:`this-page` to see
how this page was formatted. This is only a brief outline for more
please see `the Sphinx documentation <http://sphinx-doc.org/contents.html>`_


Main Titles and Subtitles
-------------------------

This is an example of a main title.

subtitles are made like this
============================

This is an example of a subtitle.

Formatting
----------

Basic Paragraph Formatting
==========================

Words can be written in *italics* or in **bold**. Text describing a specific
``computer_thing`` can be formatted as well.


Paragraph and Indentation
=========================

Much like in regular python, the indentation plays a strong role in the formatting.

For example all of this sentence will
appear on the same line.

While this sentence will appear
differently because there is an indent.

Terminal and Code Formatting
============================

Something to be run in command line can be formatted like this::

>> Some command

As can be seen above, while snippets of python on code can be done like this::

import module
print('hello world')

Notes
=====
.. note:: Notes can be added like this.

Bullet Points and Lists
=======================

* Bullet points can be added
* Just like this
* With sub-bullets like this

#. While numerical bullets
#. Can be added
#. Like this


Links, Code Display, Cross References
-------------------------------------
External Links
==============
Can be done like here for `AiiDA <www.aiida.net/>`_

Code Download
=============

Code can be downloaded like this.

Download: :download:`this example script <cheatsheet.rst>`

Code Display
============

Can be done like this. This entire document can be seen unformated below using this method.

.. literalinclude:: conf.py

.. _self-reference:

Math
====

Math formulas can be added as follows :math:`<g_i|`, see
`the Sphinx documentation on math <http://sphinx-doc.org/latest/ext/math.html#module-sphinx.ext.mathbase>`_


Cross Reference Docs
====================

Here is an example of a reference to something on the same page, :ref:`self-reference`

.. note:: References within the same document need a reference label, see `.. _self-reference:`
used in this section for an example. *Hidden in formatted page, can only be seen in the
input text.*

Cross Reference Classes and Methods
===================================

Any class can be referenced for example :py:class:`~aiida.orm.data.structure.StructureData` references the
StructureData data class.

Similarily any method can be referenced for example :py:meth:`~aiida.orm.data.structure.StructureData.append_atom`
shows the StructureData class' append atom method.

How To Format Docstrings
------------------------

Much of the work will be done automatically by Sphinx, just format the docstrings with the same syntax used here,
a few extra examples of use would include::

:param parameters: some notes on input parameters

:return returned: some note on what is returned

:raise Errors: Notes on warnings raised



Changing The Docs
-----------------

When creating a new ``.rst`` file, please:
the relevant ``index.rst`` tree. This can be done by:

* Modify relevant doc strings or ``.rst`` files in
the ``/docs/source/`` folder, not in ``/docs/build``

* Make sure that all relevant ``.rst`` files are added
to relevant ``index.rst`` files (table of contents)

* Run ``make all`` in the ``/docs/`` folder

* Fix warnings, if any

.. _this-page:

This Page
=========

.. literalinclude:: cheatsheet.rst

+ 1
- 0
src/source/index.rst View File

@@ -16,6 +16,7 @@ Guide
:maxdepth: 2
:caption: Contents:

cheatsheet
license
help



Loading…
Cancel
Save