Commit 629ffbce authored by Alan O'Cais's avatar Alan O'Cais
Browse files

Sync ES to Classical MD

parent d2bee044
_build
_templates
_static
\ No newline at end of file
_static
*.pyc
.. _readme:
=============================================
The E-CAM Electronic Structure Module Library
=============================================
======================================
The E-CAM Electronic Structure Library
======================================
This is a collection of the modules that have been created by E-CAM community within the area of Electronic Structure.
The first ESL ESDW in Zaragoza in June 2016 was the starting point for the following modules:
An example of the content of a module can be found here:
`Example module <docs/example_module/readme.rst>`__
`Example module <modules/example_module/readme.rst>`__
......@@ -117,41 +117,107 @@ todo_include_todos = True
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if on_rtd:
sys.path.insert(0, os.path.abspath('./'))
import sphinx_bootstrap_theme
html_theme = 'bootstrap'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
# Navigation bar title. (Default: ``project`` value)
'navbar_title': "Electronic Structure",
# Tab name for entire site. (Default: "Site")
'navbar_site_name': "Site",
# Tab name for the current pages TOC. (Default: "Page")
'navbar_pagenav_name': "Page",
# A list of tuples containing pages or urls to link to.
# Valid tuples should be in the following forms:
# (name, page) # a link to a page
# (name, "/aa/bb", 1) # a link to an arbitrary relative url
# (name, "http://example.com", True) # arbitrary absolute url
# Note the "1" or "True" value above as the third argument to indicate
# an arbitrary url.
# 'navbar_links': [
# ("Examples", "examples"),
# ("Link", "http://example.com", True),
# ],
# Global TOC depth for "site" navbar tab. (Default: 1)
# Switching to -1 shows all levels.
'globaltoc_depth': 2,
# Include hidden TOCs in Site navbar?
#
# Note: If this is "false", you cannot have mixed ``:hidden:`` and
# non-hidden ``toctree`` directives in the same page, or else the build
# will break.
#
# Values: "true" (default) or "false"
'globaltoc_includehidden': "true",
# HTML navbar class (Default: "navbar") to attach to <div> element.
# For black navbar, do "navbar navbar-inverse"
'navbar_class': "navbar",
# Fix navigation bar to top of page?
# Values: "true" (default) or "false"
'navbar_fixed_top': "true",
# Location of link to source.
# Options are "nav" (default), "footer" or anything else to exclude.
'source_link_position': "nav",
# Bootswatch (http://bootswatch.com/) theme.
#
# Options are nothing (default) or the name of a valid theme such
# as "amelia" or "cosmo".
#
# Example themes:
# * flatly
# * sandstone (v3 only)
# * united
# * yeti (v3 only)
'bootswatch_theme': "sandstone",
# Choose Bootstrap version.
# Values: "3" (default) or "2" (in quotes)
'bootstrap_version': "3",
}
# Add any paths that contain custom themes here, relative to this directory.
# ``get_html_theme_path`` returns a list, so you can concatenate with
# any other theme directories you would like.
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
else:
html_theme = 'default'
html_theme_options = {}
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
#html_short_title = "Demo"
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
# Path should be relative to the ``_static`` files directory.
html_logo = 'ecam_logo.png'
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
html_static_path = ["_static"]
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
......@@ -163,6 +229,8 @@ html_static_path = ['_static']
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
#html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'], }
html_sidebars = {'sidebar': ['localtoc.html', 'sourcelink.html', 'searchbox.html']}
# Additional templates that should be rendered to pages, maps page names to
# template names.
......@@ -194,20 +262,6 @@ html_static_path = ['_static']
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'E-CAMdoc'
......
.. E-CAM documentation master file, created by
sphinx-quickstart on Thu Sep 15 17:56:17 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. _readme:
=============================================
The E-CAM Electronic Structure Module Library
=============================================
This is a collection of the modules that have been created by E-CAM community within the area of Electronic Structure.
ESDW Zaragoza 2016
------------------
The first ESL ESDW in Zaragoza in June 2016 was the starting point for the modules below.
.. toctree::
:maxdepth: 1
./example_module/readme
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. E-CAM documentation master file, created by
sphinx-quickstart on Thu Sep 15 17:56:17 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. _readme:
=============================================
The E-CAM Electronic Structure Module Library
=============================================
.. sidebar:: General Information
.. contents:: :local:
* :ref:`search`
.. image:: ./images/namd.jpg
:width: 10 %
:align: left
This is a collection of the modules that have been created by E-CAM community within the area of Electronic Structure.
Extended Software Development Workshops
=======================================
ESDW Zaragoza 2016
----------------------
The first Electronic Structure ESDW in Zaragoza in June 2016 was the starting point for the modules below.
.. toctree::
:glob:
:maxdepth: 1
./modules/example_module/readme
Contributing to this documentation
==================================
GitLab account
--------------
If you do not have a (free) GitLab account yet on the E-CAM GitLab service, you'll need to get one via https://gitlab.e-cam2020.eu/ .
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.
SSH public key @ GitLab
-----------------------
You also need to register an SSH public key, so you can easily clone, push to and pull from your repository. This can be done via https://gitlab.e-cam2020.eu/profile/keys if you're logged in on GitLab.
In the following it is assumed that an SSH public key has been registered, since it is a requirement for cloning/pushing via the git protocol.
Clone your fork of the repository
---------------------------------
Clone your fork of the repository to your favorite workstation.
.. code-block:: bash
git clone ssh://git@gitlab.e-cam2020.eu:10022/<Your GitLab username>/Electronic-Structure-Modules.git
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 pull gitlab_ecam master
Keep your master branch up-to-date
----------------------------------
Make sure you update it every time you create a feature branch (see below):
.. code-block:: bash
git checkout master
git pull gitlab_ecam master
Branching
---------
Pick a branch name for your work that makes sense, so you can track things easily and make sense if you end up having several branches in flight at once (each PR is a new branch).
Examples:
``update_gromacs_module``
``new_esdw_lammps_module``
``industry_devel_module``
Create a feature branch for your work (after updating your master), and check it out
.. code-block:: bash
git checkout master
git branch BRANCH_NAME
git checkout BRANCH_NAME
Make sure to always base your features branches on master!
After creating the branch, implement your contributions: new modules, enhancements or updates to existing modules, bug fixes, structure changes, whatever you like. Make sure you commit your work, and try to do it in bite-size chunks, so the commit log remains clear.
For example:
.. code-block:: bash
git add modules/gromacs_gpu/readme.rst
git commit -m "add details on GPU support within GROMACS"
If you are working on several things at the same time, try and keep things isolated in separate branches, to keep it manageable (both for you, and for reviewing your contributions).
Contributing back your input
----------------------------
When you've finished the implementation of a particular contribution, here's how to get it into the main repository.
Push your branch to *your* copy of the repository on GitLab
.. code-block:: bash
git push origin <BRANCH_NAME>
Issue a *Merge Request* for your branch into the main repository. To do this go to https://gitlab.e-cam2020.eu/Your_GitLab_Username/Electronic-Structure-Modules/merge_requests and select the *New Merge Request* button.
Make sure the branch you just pushed is selected (not master!) issue a merge request for your branch to the master branch of the main repository.
......@@ -11,4 +11,5 @@ To include a patch file do something like the following:
:emphasize-lines: 2,9-11
:linenos:
:download:`Downloadable version of patch file <simple.patch>`
\ No newline at end of file
:download:`Downloadable version of patch file <simple.patch>`
......@@ -4,6 +4,28 @@
E-CAM example module
####################
.. sidebar:: Software Technical Information
This list is a work in progress, please help us improve it. We use *definition lists* of ReST_ to make this readable
Language
Please indicate the main languages used by the module.
Licence
Specify the licence under which the software is released.
Documentation Tool
All source code should be documented so please indicate what tool has been used for documentation. We can help you
with Doxygen and ReST but if you use other tools it might be harder for us to help if there are problems.
Application Documentation
Provide a link to any documentation.
Relevant Training Material
Add a link to any relevant training material.
.. contents:: :local:
This is an example of what a *module* for E-CAM looks like. Please add to this template any additional items that are
straightforward to fill out in the general case. You are free add any level of complexity you wish (within the bounds of
what ReST_ can do).
......@@ -13,6 +35,8 @@ and add a directory that will contain your module information. Copy this :downlo
changes back to GitLab and immediately open a merge request from your feature branch against our repository. We can
discuss your module in the merge request and help you get it accepted.
.. Add technical info as a sidebar and allow text below to wrap around it
Purpose of Module
_________________
......@@ -28,24 +52,6 @@ ______________________
If the modifications are to an existing code base then this would be the place to describe that codebase and how to get
access to it.
Software Technical Information
______________________________
This list is a work in progress, please help us improve it. We use *definition lists* of ReST_ to make this readable
Language
Please indicate the main languages used by the module
Documentation Tool
All source code should be documented so please indicate what tool has been used for documentation. We can help you
with Doxygen and ReST but if you use other tools it might be harder for us to help if there are problems.
Application Documentation
Provide a link to any documentation
Relevant Training Material
Add a link to any relevant training material
Testing
_______
......@@ -89,12 +95,14 @@ To include a patch file do something like the following:
If the patch is very long you will probably want to add it as a subpage so let's do that now
:ref:`patch`
.. toctree::
:glob:
:maxdepth: 1
patch
.. Here are the URL references used
.. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html
\ No newline at end of file
.. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html
Copyright (c) 2011-2016 Ryan Roemer
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
"""Sphinx bootstrap theme."""
import os
VERSION = (0, 4, 12)
__version__ = ".".join(str(v) for v in VERSION)
__version_full__ = __version__
def get_html_theme_path():
"""Return list of HTML theme paths."""
cur_dir = os.path.abspath(os.path.dirname(__file__))
return [cur_dir]
<li class="dropdown globaltoc-container">
<a role="button"
id="dLabelGlobalToc"
data-toggle="dropdown"
data-target="#"
href="{{ pathto(master_doc) }}">{{ theme_navbar_site_name }} <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"
role="menu"
aria-labelledby="dLabelGlobalToc">{{ toctree(maxdepth=theme_globaltoc_depth|toint, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}</ul>
</li>
{% extends "basic/layout.html" %}
{% set theme_css_files = [] %}
{% if theme_bootstrap_version == "3" %}
{% set bootstrap_version, bootstrap_additional_css, navbar_version = "3.3.6", "theme", "" %}
{% set bs_span_prefix = "col-md-" %}
{% else %}
{% set bootstrap_version, bootstrap_additional_css, navbar_version = "2.3.2", "responsive", "-2" %}
{% set bs_span_prefix = "span" %}
{% endif %}
{% if theme_bootswatch_theme and theme_bootswatch_theme != "\"\"" %}
{# BS2 needs "bootstrap-responsive.css". BS3 doesn't. #}
{% if theme_bootstrap_version == "3" %}
{% set theme_css_files = theme_css_files + [
'_static/bootswatch-' + bootstrap_version + '/' + theme_bootswatch_theme + '/bootstrap.min.css',
'_static/bootstrap-sphinx.css'
]
%}
{% else %}
{% set theme_css_files = theme_css_files + [
'_static/bootswatch-' + bootstrap_version + '/' + theme_bootswatch_theme + '/bootstrap.min.css',
'_static/bootstrap-' + bootstrap_version + '/css/bootstrap-' + bootstrap_additional_css + '.min.css',
'_static/bootstrap-sphinx.css'
]
%}
{% endif %}
{% else %}
{% set theme_css_files = theme_css_files + [
'_static/bootstrap-' + bootstrap_version + '/css/bootstrap.min.css',
'_static/bootstrap-' + bootstrap_version + '/css/bootstrap-' + bootstrap_additional_css + '.min.css',
'_static/bootstrap-sphinx.css'
]
%}
{% endif %}
{% if not bootswatch_css_custom %}
{% set bootswatch_css_custom = [] %}
{% endif %}
{% set css_files = css_files + theme_css_files + bootswatch_css_custom %}
{% set script_files = script_files + [
'_static/js/jquery-1.11.0.min.js',
'_static/js/jquery-fix.js',
'_static/bootstrap-' + bootstrap_version + '/js/bootstrap.min.js',
'_static/bootstrap-sphinx.js'
]
%}
{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and sidebars %}
{%- set bs_content_width = render_sidebar and "9" or "12"%}
{%- block doctype -%}
<!DOCTYPE html>
{%- endblock %}
{# Sidebar: Rework into our Bootstrap nav section. #}
{% macro navBar() %}
{% include "navbar" + navbar_version + ".html" %}
{% endmacro %}
{% if theme_bootstrap_version == "3" %}
{%- macro bsidebar() %}
{%- if render_sidebar %}
<div class="{{ bs_span_prefix }}3">
<div id="sidebar" class="bs-sidenav" role="complementary">
{%- for sidebartemplate in sidebars %}
{%- include sidebartemplate %}
{%- endfor %}
</div>
</div>
{%- endif %}
{%- endmacro %}
{% else %}
{%- macro bsidebar() %}
{%- if render_sidebar %}
<div class="{{ bs_span_prefix }}3">
<div id="sidebar" class="bs-sidenav well" data-spy="affix">
{%- for sidebartemplate in sidebars %}
{%- include sidebartemplate %}
{%- endfor %}
</div>
</div>
{%- endif %}
{%- endmacro %}
{% endif %}
{%- block extrahead %}
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
{% endblock %}
{# Silence the sidebar's, relbar's #}
{% block header %}{% endblock %}
{% block relbar1 %}{% endblock %}
{% block relbar2 %}{% endblock %}
{% block sidebarsourcelink %}{% endblock %}
{%- block content %}
{{ navBar() }}
<div class="container">
<div class="row">
{%- block sidebar1 %}{{ bsidebar() }}{% endblock %}
<div class="{{ bs_span_prefix }}{{ bs_content_width }} content">
{% block body %}{% endblock %}
</div>
{% block sidebar2 %} {# possible location for sidebar #} {% endblock %}
</div>
</div>
{%- endblock %}
{%- block footer %}
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
{% if theme_source_link_position == "footer" %}
<br/>
{% include "sourcelink.html" %}
{% endif %}
</p>
<p>
{%- if show_copyright %}
{%- if hasdoc('copyright') %}
{% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}<br/>
{%- else %}
{% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.{% endtrans %}<br/>
{%- endif %}
{%- endif %}
{%- if last_updated %}
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/>
{%- endif %}
{%- if show_sphinx %}
{% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}<br/>
{%- endif %}
</p>
</div>
</footer>
{%- endblock %}