About this site
These docs originally came from the Triton User Guide, but now serves as a general Aalto scientific computing guide. The intention is a good central resources for researchers, kept up to date by the whole community. Many parts are useful to the broader world, too. We encourage the community and world to all contribute when they see a need.
Sphinx is a static site generator - you can build the site on your own computer and browse the HTML. It’s automatically built and hosted by ReadTheDocs, but you don’t need to mess with that part. Github will validate basic syntax in pull requests.
See also
Technical documentation with Sphinx for an overview about how and why it’s set up like this.
Contributing
We welcome contributions via normal Github open source practices: send us a pull request.
This documentation is Open Source (CC-BY 4.0), and we welcome contributions from the community. The project is run on Github in the repository AaltoSciComp/scicomp-docs.
To contribute, you can always use the normal Github contribution mechanisms: make a pull request, issues, or comments. If you are at Aalto, you can also get direct write access. Make a github issue, then contact us in person/by email for us to confirm.
The worst contribution is one that isn’t made. Don’t worry about making things perfect: send your improvement and someone can improve the syntax/writing/etc as needed. This is also true for formatting errors - if you can’t do ReStructudedText perfectly, just do your best (and pretend it’s markdown because all the basics are similar).
When you submit a change, there is continuous testing that will notify you of errors, so that you can make changes with confidence: “wiki rules: deploy and iterate” rather than “perfect before merge”.
Contributing gives agreement to use content under the licenses (CC-BY 4.0 or CC0 for examples).
Requirements and building
Set up the environment first (example, but do as you’d like). The
basic requirements are sphinx
and sphinx_rtd_theme` which are
also in Ubuntu: (``python-sphinx
and python-sphinx-rtd-theme
):
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
Then you can build it locally to test:
$ make html
$ sphinx-autobuild . _build/html/ # starts web server that automatically updates
$ make clean check # Full rebuild and warn of important errors
HTML output is in _build/html/index.html
.
Editing
In short: find an example page and copy. To add sections, add a new page in a
subfolder. In order to appear in the sidebar, it has to be linked
from a toctree
directive. Check nearby index.rst
pages and
add there.
Recommended pages for copying:
Serial Jobs - tutorial
Python Environments with Conda - topical discussion on a certain item
/triton/apps/TEMPLATE.rst.template
is a template for an application information page.Harbor: Container registry for images and artifacts: service page.
Most common missed quirks
Double backquote for literal text, not single. (Why? Single can be assigned other purposes, like :doc: links, :ref: links, or in other projects :func: and so on. We be generic so compatible with other projects that make a different choice.):
Run ``ssh -X triton.aalto.fi`` to ...
Raw HTML links have two underscores. (Why? single underscore is some other fancy things. Most links are internal reference/docs links):
The `OpenSSH project <https://www.openssh.com/>`__ does...
Internal links have structures: they can be
:doc:
,:ref:
, etc. If you give a link to something, it knows where it is, validates it at build time, and you can give just the link and it takes the title from the target.You can set default highlighting for literal blocks, so you don’t have to do
.. code-block:: LANGUAGE
all the time:.. highlight:: console
This sets the default for all literal blocks, but you can still make a
..code-block::
for other cases (or change it partway through).For command line, use the
console
highlighting language instead ofbash
or others.console
will highlight the$
and make it not selectable so it won’t be copied.This isn’t relevant to scicomp-docs, but intersphinx lets you link directly to function/etc definitions in other Sphinx docs, by function name. (This is why rigid structure is nice). Python for SciComp heavily uses this for great effect.
ReStructured text
ReStructured Text is similar to markdown for basics, but has a more strictly defined syntax and more higher level structure. This allows more semantic markup, more power to compile into different formats (since there isn’t embedded HTML), and advanced things like indexing, permanent references, etc.
Restructured text quick reference and home.
Note: Literal inline text uses ``
instead of a single `
(second
works but gives warning).
A very quick guide is below.
Inline syntax
Inline code/monospace
, emphasis, strong emphasis
``Inline code/monospace``, *emphasis*, **strong emphasis**
Literal blocks, code highlighting
Literal blocks (= code blocks) use ::
and are intended:
Literal block
Literal block
::
Literal block
Literal blocks
Block quotes can also start with paragraph ending in double colon, like this:
Block quote
Block quotes can also start with paragraph ending in double colon,
like this::
Block quote
If you define a highlight language, it will be used as the default highlight language for every block:
.. highlight:: python
Use Python
for python. Use console
for console commands, and
include the $
before the commands. The $
won’t be selectable
so copy-and-paste works well.
Internal page links
Linking internally. If possible use a permanent reference (next
section), but you can also refer to specific files by name. Note,
that for internal links there are no trailing underscores. Internal
links can get their text from the target. Internal links are the
:doc:
domain:
:doc:`../tut/interactive.rst`
With different text: :doc:`Text <../tut/interactive.rst>`
Internal reference links
Internal links: ReST permanent references across files.
Label things this way (note only one colon):
.. _label-name:
Reference them this way:
:ref:`label-name` (recommended)
`label-name` (short, don't use, no warning if link breaks)
`Text <label-name>` (short, don't use, no warning if link breaks)
URL links
Inline link, or anonymous, or separate, or different text links. Trailing underscores indicate links. Note there should be two underscores for the raw links.
Inline `link <https://www.python.org>`__, or
anonymous__, or
separate_, or
`different text <separate_>`_ links.
Trailing underscores indicate links.
__ https://www.python.org
.. _separate: https://www.python.org
Admonitions: notes, warnings, etc.
Notes, warnings, etc.
Note
This is a note.
Warning
This is a warning.
Admonition directives have titles.
This has misc text.
Dropdown can be clicked to expand.
When it’s not important for everyone to see. :class: dropdown
sets a CSS class which gets interpreted in the HTML.
.. note::
This is a note.
.. warning::
This is a warning.
.. admonition:: Admonition directives have titles.
This has misc text.
.. admonition:: Dropdown can be clicked to expand.
:class: dropdown
When it's not important for everyone to see. ``:class: dropdown``
sets a CSS class which gets interpreted in the HTML.
Indexing
Indexing isn’t currently used.
.. index:: commit; amend
.. index::
commit
commit; message
pair: commit; amend
:index:`commit`
:index:`loop variables <pair: commit; amend>`