Sphinx cheatsheet¶
A brief overview of some of the main functions of Sphinx as used in the aiida documentation. View This Page to see how this page was formatted. This is only a brief outline for more please see the Sphinx documentation
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¶
Code Display¶
Can be done like this. This entire document can be seen unformated below using this method.
#!/usr/bin/env python
# -*- coding: utf-8 -*-
###########################################################################
# Copyright (c), The AiiDA team. All rights reserved. #
# This file is part of the AiiDA code. #
# #
# The code is hosted on GitHub at https://github.com/aiidateam/aiida_core #
# For further information on the license, see the LICENSE.txt file #
# For further information please visit http://www.aiida.net #
###########################################################################
import json
import sys
in_file = sys.argv[1]
out_file = sys.argv[2]
print "Some output from the code"
with open(in_file) as f:
in_dict = json.load(f)
out_dict = { 'sum':in_dict['x1']+in_dict['x2'] }
with open(out_file,'w') as f:
json.dump(out_dict,f)
Math¶
Math formulas can be added as follows , see the Sphinx documentation on math
Cross Reference Docs¶
Here is an example of a reference to the General comments which is on another page
Here is an example of a reference to something on the same page, Math
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 StructureData
references the
StructureData data class.
Similarily any method can be referenced for example append_atom()
shows the StructureData class’ append atom method.
Table of Contents Docs and Code¶
Table of Contents for Docs¶
An example of the table of contents syntax for the GIT cheatsheet can be seen here note that these are especially important in the global structure of the document, as found in index.rst files.
- GIT cheatsheet
- Interesting online resources
- Set the push default behavior to push only the current branch
- View commits that would be pushed
- Switch to another branch
- Associate a local and remote branch
- Branch renaming
- Create a new (lightweight) tag
- Create a new branch from a given tag
- Disallow a branch deletion, or committing to a branch, on GitHub
- Merge from a different repository
Note
The maxdepth parameter can be used to change how deep the title indexing goes. See This Page.
Table of Contents for Code¶
Table of contents, that cross reference code, can be done very similarly to how it is done for documents. For example the parser docs can be indexed like this
Automodules Example¶
This module defines the main data structures used by Calculations.
-
class
aiida.common.datastructures.
CalcInfo
(init=None)[source] This object will store the data returned by the calculation plugin and to be passed to the ExecManager.
In the following descriptions all paths have to be considered relative
- retrieve_list: a list of strings or tuples that indicate files that are to be retrieved from the remote
after the calculation has finished and stored in the repository in a FolderData. If the entry in the list is just a string, it is assumed to be the filepath on the remote and it will be copied to ‘.’ of the repository with name os.path.split(item)[1] If the entry is a tuple it is expected to have the following format
(‘remotepath’, ‘localpath’, depth)
If the ‘remotepath’ is a file or folder, it will be copied in the repository to ‘localpath’. However, if the ‘remotepath’ contains file patterns with wildcards, the ‘localpath’ should be set to ‘.’ and the depth parameter should be an integer that decides the localname. The ‘remotepath’ will be split on file separators and the local filename will be determined by joining the N last elements, where N is given by the depth variable.
Example: (‘some/remote/path/files/pattern*[0-9].xml’, ‘.’, 2)
Will result in all files that match the pattern to be copied to the local repository with path
‘files/pattern*[0-9].xml’
- retrieve_temporary_list: a list of strings or tuples that indicate files that will be retrieved
and stored temporarily in a FolderData, that will be available only during the parsing call. The format of the list is the same as that of ‘retrieve_list’
- retrieve_singlefile_list: a list of tuples with format
(‘linkname_from calc to singlefile’, ‘subclass of singlefile’, ‘filename’) Each tuple represents a file that will be retrieved from cluster and saved in SinglefileData nodes
local_copy_list: a list of tuples with format (‘localabspath’, ‘relativedestpath’)
remote_copy_list: a list of tuples with format (‘remotemachinename’, ‘remoteabspath’, ‘relativedestpath’)
remote_symlink_list: a list of tuples with format (‘remotemachinename’, ‘remoteabspath’, ‘relativedestpath’)
codes_info: a list of dictionaries used to pass the info of the execution of a code
codes_run_mode: a string used to specify the order in which multi codes can be executed
-
class
aiida.common.datastructures.
CalcState
[source]
-
class
aiida.common.datastructures.
CodeInfo
(init=None)[source] This attribute-dictionary contains the information needed to execute a code. Possible attributes are:
cmdline_params
: a list of strings, containing parameters to be written on the command line right after the call to the code, as for example:code.x cmdline_params[0] cmdline_params[1] ... < stdin > stdout
stdin_name
: (optional) the name of the standard input file. Note, it is only possible to use the stdin with the syntax:code.x < stdin_name
If no stdin_name is specified, the string “< stdin_name” will not be passed to the code. Note: it is not possible to substitute/remove the ‘<’ if stdin_name is specified; if that is needed, avoid stdin_name and use instead the cmdline_params to specify a suitable syntax.
stdout_name
: (optional) the name of the standard output file. Note, it is only possible to pass output to stdout_name with the syntax:code.x ... > stdout_name
If no stdout_name is specified, the string “> stdout_name” will not be passed to the code. Note: it is not possible to substitute/remove the ‘>’ if stdout_name is specified; if that is needed, avoid stdout_name and use instead the cmdline_params to specify a suitable syntax.
stderr_name
: (optional) a string, the name of the error file of the code.join_files
: (optional) if True, redirects the error to the output file. If join_files=True, the code will be called as:code.x ... > stdout_name 2>&1
otherwise, if join_files=False and stderr is passed:
code.x ... > stdout_name 2> stderr_name
withmpi
: if True, executes the code with mpirun (or another MPI installed on the remote computer)code_uuid
: the uuid of the code associated to the CodeInfo
-
class
aiida.common.datastructures.
CodeRunmode
[source]
-
class
aiida.common.datastructures.
WorkflowDataType
[source]
-
class
aiida.common.datastructures.
WorkflowDataValueType
[source]
-
class
aiida.common.datastructures.
WorkflowState
[source]
-
aiida.common.datastructures.
sort_states
(list_states, use_key=False)[source] Given a list of state names, return a sorted list of states (the first is the most recent) sorted according to their logical appearance in the DB (i.e., NEW before of SUBMITTING before of FINISHED).
Note
The order of the internal variable _sorted_datastates is used.
Parameters: - list_states – a list (or tuple) of state strings.
- use_key – if True, expects that each element is not just a string, but a pair (someobject, string). Only string is used to sort (should be the state string), and only someobject is returned in the final list.
Returns: a sorted list of the given data states.
Raises: ValueError – if any of the given states is not a valid state.
Note
A :noindex: directive was added to avoid duplicate object description for this example. Do not put the keyword in a real documentation.
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 relevantindex.rst
files (table of contents) - Run
make all
in the/docs/
folder - Fix warnings, if any
This Page¶
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 <devel_tutorial/sum_executable.py>`
Code Display
============
Can be done like this. This entire document can be seen unformated below using this method.
.. literalinclude:: devel_tutorial/sum_executable.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 the :ref:`structure_tutorial` which is on *another page*
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.
Table of Contents Docs and Code
-------------------------------
Table of Contents for Docs
==========================
An example of the table of contents syntax for the :ref:`git-cheatsheet` can be seen here
note that these are especially important in the global structure of the
document, as found in index.rst files.
.. toctree::
:maxdepth: 2
git_cheatsheet
.. note:: The `maxdepth` parameter can be used to change how deep the title indexing goes. See :ref:`this-page`.
Table of Contents for Code
==========================
Table of contents, that cross reference code, can be done very similarly to how
it is done for documents. For example the parser docs can be indexed like this
.. toctree::
:maxdepth: 1
aiida.orm <../apidoc/aiida.orm>
../apidoc/aiida.utils
Automodules Example
====================
.. toctree::
:maxdepth: 2
.. automodule:: aiida.common.datastructures
:members:
:noindex:
.. note:: A `:noindex:` directive was added to avoid duplicate object
description for this example. Do not put the keyword in a real
documentation.
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:: sphinx_cheatsheet.rst