Commit 2db1650f authored by Francesco Fracchia's avatar Francesco Fracchia
parents 4c9cd570 2100e719
Pipeline #413 passed with stages
in 27 seconds
image: plaindocs/docker-sphinx
pages:
script:
- sudo apt-get -y install dvipng
- make html
- mv _build/html/ public/
artifacts:
paths:
- public
only:
- master
......@@ -35,7 +35,7 @@ extensions = [
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.imgmath',
'sphinx.ext.pngmath',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
]
......@@ -83,7 +83,7 @@ language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build','README.rst']
exclude_patterns = ['_build', 'README.rst']
# The reST default role (used for this markup: `text`) to use for all
# documents.
......@@ -118,6 +118,9 @@ todo_include_todos = True
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
# Let's default this to on since GitLab supports building the docs
on_rtd= True
if on_rtd:
sys.path.insert(0, os.path.abspath('./'))
import sphinx_bootstrap_theme
......@@ -171,7 +174,7 @@ if on_rtd:
# Location of link to source.
# Options are "nav" (default), "footer" or anything else to exclude.
'source_link_position': "nav",
'source_link_position': "footer",
# Bootswatch (http://bootswatch.com/) theme.
#
......
.. _contributing:
.. sidebar:: General Information
.. contents:: :local:
* :ref:`search`
=======================================
How to contribute to this documentation
=======================================
.. _contributing:
==================
How to contribute?
==================
This webpage is actually a repository of files that document application development efforts during the pilot projects
and Extended Software Development Workshops (ESDWs) of E-CAM. How you contribute will depend on whether you are an
attendee at and ESDW or working on a pilot project.
In both cases you will simply be adding a simple text file that uses ReST_ and we have prepared some examples to help
you get started:
* :ref:`example`
* :ref:`pilot`
You will find these examples within the repository of this documentation under the directory *modules*. You should make
a copy of the appropriate directory (renaming it).
Contribution Guidelines
=======================
GitLab account
--------------
......@@ -18,7 +34,7 @@ If you do not have a (free) GitLab account yet on the E-CAM GitLab service, you'
Fork the repository
-------------------
First, you'll need to fork the repository on GitLab you want to work with. Go to https://gitlab.e-cam2020.eu/E-CAM/Electronic-Structure-Modules , and click the grey 'Fork' button under the repository name.
First, you'll need to fork the repository on GitLab you want to work with. Go to https://gitlab.e-cam2020.eu/e-cam/Electronic-Structure-Modules , and click the grey 'Fork' button under the repository name.
SSH public key @ GitLab
-----------------------
......@@ -41,7 +57,7 @@ Pull the master branch from the main repository:
.. code-block:: bash
cd Electronic-Structure-Modules
git remote add gitlab_ecam https://git@gitlab.e-cam2020.eu/E-CAM/Electronic-Structure-Modules.git
git remote add gitlab_ecam https://git@gitlab.e-cam2020.eu/e-cam/Electronic-Structure-Modules.git
git pull gitlab_ecam master
Keep your master branch up-to-date
......@@ -151,3 +167,4 @@ Now that everything is in sync, you can edit your update your files, when you ar
The Merge Request will now be automatically updated with the changed files.
.. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html
\ No newline at end of file
......@@ -3,7 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. comment this line _readme:
.. _readme:
=============================================
The E-CAM Electronic Structure Module Library
......@@ -15,13 +15,13 @@ The E-CAM Electronic Structure Module Library
* :ref:`search`
.. image:: ./images/namd.jpg
:width: 10 %
.. figure:: ./images/wake_nova-rgb.pdf
:figwidth: 25 %
:align: left
This is a collection of the modules that have been created by E-CAM community within the area of Electronic Structure. This documentation is created using ReStructured Text and the git repository for the documentation
source files can be found at
https://gitlab.e-cam2020.eu/E-CAM/Electronic-Structure-Modules which are
https://gitlab.e-cam2020.eu/e-cam/Electronic-Structure-Modules which are
public and open to contributions.
In the context of E-CAM, the definition of a software module is any piece of software that could be of use to the E-CAM community and that encapsulates some additional functionality, enhanced performance or improved usability for people performing computational simulations in the domain areas of interest to us.
......@@ -77,6 +77,24 @@ The ESDW in San Sebastian in September 2016 was the starting point for the modul
./modules/Use_WS_Distance/readme
./modules/Test-Suite-Travis-CI-Integration/readme
Pilot Projects
==============
One of primary activity of E-CAM is to engage with pilot projects with industrial partners. These projects are conceived
together with the partner and typically are to facilitate or improve the scope of computational simulation within the
partner. The related code development for the pilot projects are open source (where the licence of the underlying
software allows this) and are described in the modules associated with the pilot projects.
Below is a list of the current pilot projects within E-CAM:
.. toctree::
:glob:
:maxdepth: 1
./modules/example_pilot/readme
./modules/Geomoltools/readme
Contributing to this documentation
==================================
......@@ -86,5 +104,5 @@ This documentation is completely open and we welcome both internal and external
:glob:
:maxdepth: 2
./contributing.rst
./contributing
###########
Geomoltools
###########
.. sidebar:: Software Technical Information
This section describes the module Geomoltools.
Language
Fortran 95
Documentation Tool
Sphinx, ReStructuredText
Relevant Training Material
See usage examples in the ``tutorial`` directory.
Licence
GNU General Public License (GPL) version 2.
.. contents:: :local:
Purpose of Module
_________________
Geomoltools is a set of computer codes designed to manipulate molecules.
From simple changes of coordinates (Z-matrix to XYZ coordinates and *vice versa*)
to more complicated operations as the generation of different stacking
arrangements between molecules are quick and easy to perform.
Background Information
______________________
Geomoltools is a set of standalone codes to be employed independently
or taking part in the development of a more general project.
Installation
____________
The module does not need installation because is formed by independent pieces.
The dependency of each single code with common subroutines are managed in the
Makefile file, which leds an easy and straightforward compilation of the
desired codes.
Testing
_______
In the ``tutorial`` directory input/output files for each code are found
and constitute examples of test and usage.
Source Code
___________
The package, including all the files as well as technical help, can be found in the `E-CAM Gitlab`__ webpage.
.. __: https://gitlab.e-cam2020.eu/plesiat/geomoltools
......@@ -70,7 +70,7 @@ Testing
_______
Libescdf contains several unit tests that can be used to check the
compilation and to perform regression testing. These tests can be
compilation and to perform regression testing. Check (version>=0.9.4) is required for instalation and testing. These tests can be
executed by doing::
$ make check
......
This diff is collapsed.
.. _patch_extreme:
#####################
Patch file for module
#####################
To include a patch file do something like the following:
.. literalinclude:: ./simple.patch
:language: c
:emphasize-lines: 2,9-11
:linenos:
:download:`Downloadable version of patch file <simple.patch>`
.. In ReStructured Text (ReST) indentation and spacing are very important (it is how ReST knows what to do with your
document). For ReST to understand what you intend and to render it correctly please to keep the structure of this
template. Make sure that any time you use ReST syntax (such as for ".. sidebar::" below), it needs to be preceded
and followed by white space (if you see warnings when this file is built they this is a common origin for problems).
.. Firstly, let's add technical info as a sidebar and allow text below to wrap around it. This list is a work in
progress, please help us improve it. We use *definition lists* of ReST_ to make this readable.
.. sidebar:: Software Technical Information
Name
Name of the relevant software.
Language
Please indicate the primary language(s) used by the module. Please also state if interfaces for other languages are
available.
Licence
Specify the licence under which the software is released. Provide a link to the full online description of the
licence. You'll find descriptions of the most common licences at https://opensource.org/licenses .
An example here would be: `GPL <https://opensource.org/licenses/gpl-license>`_
Documentation Tool
All source code created for this module should be documented so please indicate what tool has been used for
documentation. Doxygen covers most languages but for Fortran you might want to use
`Ford <http://fortranwiki.org/fortran/show/FORD>`_, for Python ReST_, etc.
Application Documentation
Provide a link to any documentation for the application.
Relevant Training Material
Add a link to any relevant training material. If there currently is none then say 'Not currently available.'
.. In the next line you have the name of how this module will be referenced in the main documentation (which you can
reference, in this case, as ":ref:`example`"). You *MUST* change the reference below from "example" to something
unique otherwise you will cause cross-referencing errors. The reference must come right before the heading for the
reference to work (so don't insert a comment between).
.. _extreme_example:
############################
E-CAM example extreme module
############################
.. Let's add a local table of contents to help people navigate the page
.. contents:: :local:
.. Add an abstract for a *general* audience here. Write a few lines that explains the "helicopter view" of why you are
creating this module. For example, you might say that "This module is a stepping stone to incorporating XXXX effects
into YYYY process, which in turn should allow ZZZZ to be simulated. If successful, this could make it possible to
produce compound AAAA while avoiding expensive process BBBB and CCCC."
This is an example of what a *module* for E-CAM looks like. The original source of this page (:download:`readme.rst`)
contains lots of additional comments to help you create your module (and understand ReST_ syntax) so please use this as
a starting point. You are free add any level of complexity you wish (within the bounds of what ReST_ can do). More
general instructions for making your contribution can be found in ":ref:`contributing`".
Remember that for a module to be accepted into the E-CAM repository, your source code changes in the target application
must pass a number of acceptance criteria:
* Style *(use meaningful variable names, no global variables,...)*
* Source code documentation *(each function should be documented with each argument explained)*
* Tests *(everything you add should have either unit or regression tests)*
* Performance *(If what you introduce has a significant computational load you should make some performance optimisation
effort using an appropriate tool. You should be able to verify that your changes have not introduced unexpected
performance penalties, are threadsafe if needed,...)*
Purpose of Module
_________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
Give a brief overview of why the module is/was being created, explaining a little of the scientific background and how
it fits into the larger picture of what you want to achieve.
If needed you can include latex mathematics like
:math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}`
which won't show up on GitLab/GitHub but will in final online documentation.
If you want to add a citation, such as [CIT2004]_. Note that citations may get rearranged, e.g., to the bottom of the
"page".
.. [CIT2004] A citation (as often used in journals).
Background Information
______________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
If the modifications are to an existing code base (which is typical) then this would be the place to name that
application. List any relevant urls and explain how to get access to that code. There needs to be enough information
here so that the person reading knows where to get the source code for the application, what version this information is
relevant for, whether this requires any additional patches/plugins, etc.
Overall, this module is supposed to be self-contained, but linking to specific URLs with more detailed information is
encouraged. In other words, the reader should not need to do a websearch to understand the context of this module, all
the links they need should be already in this module.
Building and Testing
____________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
Provide the build information for the module here and explain how tests are run. This needs to be adequately detailed,
explaining if necessary any deviations from the normal build procedure of the application (and links to information
about the normal build process needs to be provided).
Source Code
___________
.. Notice the syntax of a URL reference below `Text <URL>`_
Here link the source code *that was created for the module*. If you are using Github or GitLab and the `Gitflow Workflow
<https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow>`_ you can point to your feature branch.
Linking to your pull/merge requests is even better. Otherwise you can link to the explicit commits. In this example I'm
using a patch file to highlight my source code changes, for that reason I need to explain what code (including exact
version information), the source code is for.
You can create a similar patch file by (for example if you are using git for your version control) making your changes
for the module in a feature branch and then doing something like the following:
.. Don't forget the white space around the "literal block" (a literal block keeps all spacing and is a good way to
include terminal output, file contents, etc.)
::
[adam@mbp2600 example (master)]$ git checkout -b tmpsquash
Switched to a new branch "tmpsquash"
[adam@mbp2600 example (tmpsquash)]$ git merge --squash newlines
Updating 4d2de39..b6768b2
Fast forward
Squash commit -- not updating HEAD
test.txt | 2 ++
1 files changed, 2 insertions(+), 0 deletions(-)
[adam@mbp2600 example (tmpsquash)]$ git commit -a -m "My squashed commits"
[tmpsquash]: created 75b0a89: "My squashed commits"
1 files changed, 2 insertions(+), 0 deletions(-)
[adam@mbp2600 example (tmpsquash)]$ git format-patch master
0001-My-squashed-commits.patch
To include a patch file do something like the following (take a look at the source code of this document to see the
syntax required to get this):
.. Below I am telling Sphinx that the included file is C code, if possible it will then do syntax highlighting. I can
even emphasise partiuclar lines (here 2 and 9-11)
.. literalinclude:: ./simple.patch
:language: c
:emphasize-lines: 2,9-11
:linenos:
If the patch is very long you will probably want to add it as a subpage which can be done as follows
.. toctree::
:glob:
:maxdepth: 1
patch
.. Remember to change the reference "patch" for something unique in your patch file subpage or you will have
cross-referencing problems
you can reference it with :ref:`patch`
.. Here are the URL references used (which is alternative method to the one described above)
.. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html
Always remember that a good patch file should have a comment inside about what the patch is for....just like this
--- hello.c 2014-10-07 18:17:49.000000000 +0530
+++ hello_new.c 2014-10-07 18:17:54.000000000 +0530
@@ -1,5 +1,6 @@
#include <stdio.h>
-int main() {
+int main(int argc, char *argv[]) {
printf("Hello World\n");
+ return 0;
}
\ No newline at end of file
.. _patch_pilot:
#####################
Patch file for module
#####################
To include a patch file do something like the following:
.. literalinclude:: ./simple.patch
:language: c
:emphasize-lines: 2,9-11
:linenos:
:download:`Downloadable version of patch file <simple.patch>`
.. In ReStructured Text (ReST) indentation and spacing are very important (it is how ReST knows what to do with your
document). For ReST to understand what you intend and to render it correctly please to keep the structure of this
template. Make sure that any time you use ReST syntax (such as for ".. sidebar::" below), it needs to be preceded
and followed by white space (if you see warnings when this file is built they this is a common origin for problems).
.. Firstly, let's add technical info as a sidebar and allow text below to wrap around it. This list is a work in
progress, please help us improve it. We use *definition lists* of ReST_ to make this readable.
.. sidebar:: Software Technical Information
Name
Name of the relevant software.
Language
Please indicate the primary language(s) used by the module. Please also state if interfaces for other languages are
available.
Licence
Specify the licence under which the software is released. Provide a link to the full online description of the
licence. You'll find descriptions of the most common licences at https://opensource.org/licenses .
An example here would be: `GPL <https://opensource.org/licenses/gpl-license>`_
Documentation Tool
All source code created for this module should be documented so please indicate what tool has been used for
documentation. Doxygen covers most languages but for Fortran you might want to use
`Ford <http://fortranwiki.org/fortran/show/FORD>`_, for Python ReST_, etc.
Application Documentation
Provide a link to any documentation for the application.
Relevant Training Material
Add a link to any relevant training material. If there currently is none then say 'Not currently available.'
.. In the next line you have the name of how this module will be referenced in the main documentation (which you can
reference, in this case, as ":ref:`example`"). You *MUST* change the reference below from "example" to something
unique otherwise you will cause cross-referencing errors. The reference must come right before the heading for the
reference to work (so don't insert a comment between).
.. _pilot_example:
##########################
E-CAM example pilot module
##########################
.. Let's add a local table of contents to help people navigate the page
.. contents:: :local:
.. Add an abstract for a *general* audience here. Write a few lines that explains the "helicopter view" of why you are
creating this module. For example, you might say that "This module is a stepping stone to incorporating XXXX effects
into YYYY process, which in turn should allow ZZZZ to be simulated. If successful, this could make it possible to
produce compound AAAA while avoiding expensive process BBBB and CCCC."
This is an example of what a *module* for E-CAM looks like. The original source of this page (:download:`readme.rst`)
contains lots of additional comments to help you create your module (and understand ReST_ syntax) so please use this as
a starting point. You are free add any level of complexity you wish (within the bounds of what ReST_ can do). More
general instructions for making your contribution can be found in ":ref:`contributing`".
Remember that for a module to be accepted into the E-CAM repository, your source code changes in the target application
must pass a number of acceptance criteria:
* Style *(use meaningful variable names, no global variables,...)*
* Source code documentation *(each function should be documented with each argument explained)*
* Tests *(everything you add should have either unit or regression tests)*
* Performance *(If what you introduce has a significant computational load you should make some performance optimisation
effort using an appropriate tool. You should be able to verify that your changes have not introduced unexpected
performance penalties, are threadsafe if needed,...)*
Purpose of Module
_________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
Give a brief overview of why the module is/was being created, explaining a little of the scientific background and how
it fits into the larger picture of what you want to achieve.
If needed you can include latex mathematics like
:math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}`
which won't show up on GitLab/GitHub but will in final online documentation.
If you want to add a citation, such as [CIT2003]_. Note that citations may get rearranged, e.g., to the bottom of the
"page".
.. [CIT2003] A citation (as often used in journals).
Background Information
______________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
If the modifications are to an existing code base (which is typical) then this would be the place to name that
application. List any relevant urls and explain how to get access to that code. There needs to be enough information
here so that the person reading knows where to get the source code for the application, what version this information is
relevant for, whether this requires any additional patches/plugins, etc.
Overall, this module is supposed to be self-contained, but linking to specific URLs with more detailed information is
encouraged. In other words, the reader should not need to do a websearch to understand the context of this module, all
the links they need should be already in this module.
Building and Testing
____________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
Provide the build information for the module here and explain how tests are run. This needs to be adequately detailed,
explaining if necessary any deviations from the normal build procedure of the application (and links to information
about the normal build process needs to be provided).
Source Code
___________
.. Notice the syntax of a URL reference below `Text <URL>`_
Here link the source code *that was created for the module*. If you are using Github or GitLab and the `Gitflow Workflow
<https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow>`_ you can point to your feature branch.
Linking to your pull/merge requests is even better. Otherwise you can link to the explicit commits. In this example I'm
using a patch file to highlight my source code changes, for that reason I need to explain what code (including exact
version information), the source code is for.
You can create a similar patch file by (for example if you are using git for your version control) making your changes
for the module in a feature branch and then doing something like the following:
.. Don't forget the white space around the "literal block" (a literal block keeps all spacing and is a good way to
include terminal output, file contents, etc.)
::
[adam@mbp2600 example (master)]$ git checkout -b tmpsquash
Switched to a new branch "tmpsquash"
[adam@mbp2600 example (tmpsquash)]$ git merge --squash newlines
Updating 4d2de39..b6768b2
Fast forward
Squash commit -- not updating HEAD
test.txt | 2 ++
1 files changed, 2 insertions(+), 0 deletions(-)
[adam@mbp2600 example (tmpsquash)]$ git commit -a -m "My squashed commits"
[tmpsquash]: created 75b0a89: "My squashed commits"
1 files changed, 2 insertions(+), 0 deletions(-)
[adam@mbp2600 example (tmpsquash)]$ git format-patch master
0001-My-squashed-commits.patch
To include a patch file do something like the following (take a look at the source code of this document to see the
syntax required to get this):
.. Below I am telling Sphinx that the included file is C code, if possible it will then do syntax highlighting. I can
even emphasise partiuclar lines (here 2 and 9-11)
.. literalinclude:: ./simple.patch
:language: c
:emphasize-lines: 2,9-11
:linenos:
If the patch is very long you will probably want to add it as a subpage which can be done as follows
.. toctree::
:glob:
:maxdepth: 1
patch
.. Remember to change the reference "patch" for something unique in your patch file subpage or you will have
cross-referencing problems
you can reference it with :ref:`patch`
.. Here are the URL references used (which is alternative method to the one described above)
.. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html
Always remember that a good patch file should have a comment inside about what the patch is for....just like this
--- hello.c 2014-10-07 18:17:49.000000000 +0530
+++ hello_new.c 2014-10-07 18:17:54.000000000 +0530
@@ -1,5 +1,6 @@
#include <stdio.h>
-int main() {
+int main(int argc, char *argv[]) {
printf("Hello World\n");
+ return 0;
}
\ No newline at end of file
.. In ReStructured Text (ReST) indentation and spacing are very important (it is how ReST knows what to do with your
document). For ReST to understand what you intend and to render it correctly please to keep the structure of this