MDA-style docs (#70)

* Added mdacli logo
* change style to MDAnalysis documentation
* improve landing page
* update dependencies for docs
* removed stupid macOS .DS_Store file
* Update AUTHORS and CHANGELOG

Co-authored-by: joaomcteixeira <[email protected]>
Co-authored-by: Philip Loche <[email protected]>

devtools/docs_requirements.txt

@@ -1,5 +1,6 @@
 sphinx>=2.2
-sphinx-py3doc-enhanced-theme
+sphinx-rtd-theme
+sphinx-sitemap
 sphinx-argparse
 CommonMark
 mock

docs/AUTHORS.rst

@@ -3,3 +3,4 @@ Authors
 
 * Philip Loche (`github <https://github.com/PicoCentauri>`_)
 * Joao M. C. Teixeira (`webpage <https://bit.ly/joaomcteixeira>`_, `github <https://github.com/joaomcteixeira>`_)
+* Oliver Beckstein (`webpage <https://becksteinlab.physics.asu.edu>`_, `github <https://github.com/orbeckst>`_)

docs/CHANGELOG.rst

@@ -2,6 +2,11 @@
 Changelog
 =========
 
+new_version
+-----------
+
+* MDA-style documentation pages (#70)
+
 v0.1.2 (2021-11-18)
 ------------------------------------------
 

docs/rst/_static/custom.css

@@ -0,0 +1,206 @@
+/* custom MDAnalysis styling (User Guide theme) */
+
+/* See https://github.com/MDAnalysis/mdanalysis/wiki/MDAnalysis-theme-colours */
+/* MDAnalysis orange: #FF9200 */
+/* MDAnalysis gray: #808080 */
+/* MDAnalysis white: #FFFFFF */
+/* MDAnalysis black: #000000 */
+/* Darker orange: e76900 */
+/* Even darker orange: #a24900 */
+/* RTD dark grey: #343131 */
+/* RTD light grey: #e6e6e6 */
+
+/* -- page layout --------------------------------------------------------- */
+
+body {
+    font-family: 'PT Sans', Helvetica, Arial, 'sans-serif';
+    font-size: 17px;    
+}
+
+div.body {
+    color: #000000;
+}
+
+div.sphinxsidebar a:hover {
+    text-decoration: none !important;
+}
+
+div.sphinxsidebar p {
+    color: #808080;
+}
+
+/* Home MDAnalysis colour */
+.wy-side-nav-search > a {
+    color: #343131;
+}
+
+/* Side MDAnalysis version colour */
+.wy-side-nav-search > div.version {
+    color: #808080;
+}
+
+/* Menubar caption colour */
+div.wy-menu-vertical span.caption-text {
+    color: #FF9200;
+}
+
+/* Mobile layout menubar option */
+nav.wy-nav-top {
+    background: #343131;
+}
+
+/* Menu search bar outline (default blue) */
+.wy-side-nav-search input[type="text"] {
+    border-color: #808080;
+}
+
+
+/* -- body styles --------------------------------------------------------- */
+
+/* Different coloured links for sidebar vs body) */
+div.rst-content a {
+    color: #FF9200;
+    text-decoration: none;
+}
+
+div.rst-content a:visited {
+    color: #FF9200;
+}
+
+a:hover {
+    color: #FF9200 !important;
+    text-decoration: underline;
+}
+
+
+pre, tt, code {
+    font-family: Menlo, Monaco, 'Courier New', monospace
+}
+
+
+div.body h1 {
+    font-weight: bolder;
+}
+
+a.headerlink {
+    color: #808080;
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+
+a.headerlink:hover {
+    background-color: #808080;
+    color: #fff;
+}
+
+/* ------- admonition boxes ------- */
+
+div.admonition {
+    margin: 10px 0px;
+    padding: 10px 10px;
+}
+
+div.admonition p.admonition-title {
+    font-size: 100%;
+    font-weight: bolder;
+}
+
+/* ----- Tables ----- */
+
+/* override table width restrictions */
+/* wrap tables instead of scrolling */
+@media screen and (min-width: 767px) {
+
+    .wy-table-responsive table td, .wy-table-responsive table th {
+       /* !important prevents the common CSS stylesheets from overriding
+          this as on RTD they are loaded after this stylesheet */
+       white-space: normal !important;
+    }
+
+    .wy-table-responsive {
+       overflow: visible !important;
+       max-width: 100% !important;
+    }
+ }
+
+/* ----- Field lists ------ */
+
+.section > dl.field-list {
+    display: flex;
+    flex-wrap: wrap;
+    margin: 0;
+    padding: 0;
+}
+
+dl.field-list > dt::after {
+    content: ":";
+}
+
+.rst-content dl:not(.docutils) dt {
+    background: none;
+    color: #000000;
+    border-top: none;
+}
+
+.section > dl.field-list dt {
+    margin: 0;
+    padding: 0;
+    flex-basis: 20%;
+    display: block;
+}
+
+.section > dl.field-list > dd {
+    flex-basis: 70%;
+    margin: 0;
+}
+
+.section > dl.field-list > dd p {
+    margin: 0;
+}
+
+/* ----- MDAnalysis coloured elements ------ */
+
+.rst-content dl.class dt, .rst-content dl.function dt {
+    color: #ca6500;
+    background: #FFEBD0;
+    border-top: solid 3px #FF9200;
+}
+
+.rst-content .viewcode-link, .rst-content .viewcode-back {
+    color: #808080;
+}
+
+.rst-content .guilabel {
+    background: #efefef;
+    border: 1px solid #808080;
+}
+
+
+.rst-content .seealso p.admonition-title {
+    background: #808080;
+}
+
+.rst-content .seealso {
+    background: #e3e3e3;
+}
+
+.rst-content  .error p.admonition-title, .rst-content  .warning p.admonition-title {
+    background: #F45F4B;
+}
+
+.rst-content .error, .rst-content .warning {
+    background: #FFEEED;
+}
+
+.rst-content .caution p.admonition-title, .rst-content .note p.admonition-title, .rst-content .important p.admonition-title  {
+    background: #FF9200;
+}
+
+.rst-content .caution, .rst-content .note, .rst-content .important {
+    background: #FFEBD0;
+}
+
+.rst-content code:not(.xref).literal {
+    color: #ca6500;
+}

docs/rst/_static/logos/AUTHOR

@@ -0,0 +1,21 @@
+The original MDAnalysis 'Atom' logo was created by Christian Beckstein.
+The mdacli logo is a derivative of the 'Atom' logo and is
+
+Copyright (c) 2021 "The MDAnalysis Development Team and NumFOCUS"
+
+mdacli logo is made available under a
+Creative Commons Attribution-NoDerivs 3.0 Unported License.
+To view a copy of this license, visit
+http://creativecommons.org/licenses/by-nd/3.0/ or send a letter to Creative
+Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.
+
+The mdacli logo is contained in the files
+
+mdacli-logo-square.pdf  
+mdacli-logo-square.png  
+mdacli-logo.pdf  
+mdacli-logo.png
+
+The mdanalysis-logo.ico file is a version of the MDAnalysis 'Atom' logo, which
+is also made available under CC-BY-ND 3.0.
+

docs/rst/_templates/footer.html

@@ -0,0 +1,11 @@
+{% extends "!footer.html" %}
+
+{% block extrafooter %}
+{{ super() }}
+<div class="footer"><p>Please see
+    our <a href="https://www.mdanalysis.org/pages/privacy/">Privacy Policy</a>
+    to learn how <a href="https://www.mdanalysis.org">MDAnalysis</a> collects data.</p>
+    <script data-goatcounter="https://mdanalysis.goatcounter.com/count"
+        async src="//gc.zgo.at/count.js"></script>
+</div>
+{% endblock %}

docs/rst/conf.py

@@ -6,7 +6,7 @@
 import mock
 import sys
 
-import sphinx_py3doc_enhanced_theme
+import sphinx_rtd_theme
 
 
 # activate if there are dependencies
@@ -15,6 +15,8 @@
     'MDAnalysis',
     'MDAnalysis.analysis',
     'MDAnalysis.analysis.base',
+    'MDAnalysis.transformations',
+    'MDAnalysis.transformations.boxdimensions',
     'numpy',
     ]
 
@@ -33,8 +35,13 @@
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'sphinx.ext.autosectionlabel',
+    'sphinx_rtd_theme',
+    'sphinx_sitemap',
     ]
 
+# for sitemap with https://github.com/jdillard/sphinx-sitemap
+site_url = "https://www.mdanalysis.org/mdacli/"
+
 todo_include_todos = True
 
 exclude_patterns = [
@@ -52,12 +59,13 @@
 master_doc = 'index'
 project = 'mdacli'
 year = '2021'
-author = 'Philip Loche and Joao MC Teixeira'
+author = 'Philip Loche, Joao MC Teixeira and Oliver Beckstein'
 copyright = '{0}, {1}'.format(year, author)
 version = release = '0.1.2'
 
 pygments_style = 'trac'
-templates_path = ['.']
+templates_path = ['_templates']
+
 extlinks = {
     'issue': ('https://github.com/MDAnalysis/mdacli/cissues/%s', '#'),  # noqa: E501
     'pr': ('https://github.com/MDAnalysis/mdacli/pull/%s', 'PR #'),  # noqa: E501
@@ -71,19 +79,31 @@
     r'https://codecov.io/gh/PicoCentauri/mda_cli/*',
     ]
 
-html_theme = "sphinx_py3doc_enhanced_theme"
-html_theme_path = [sphinx_py3doc_enhanced_theme.get_html_theme_path()]
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_theme_options = {
-    'githuburl': 'https://github.com/MDAnalysis/mdacli',
-    }
-
+    'canonical_url': '',
+    'logo_only': True,
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    'style_external_links': False,
+    'style_nav_header_background': 'white',
+    # Toc options
+    'collapse_navigation': True,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False,
+}
 html_use_smartypants = True
 html_last_updated_fmt = '%b %d, %Y'
 html_split_index = False
-html_sidebars = {
-    '**': ['searchbox.html', 'globaltoc.html', 'sourcelink.html'],
-    }
 html_short_title = '%s-%s' % (project, version)
+html_logo = "_static/logos/mdacli-logo.png"
+html_favicon = "_static/logos/mdanalysis-logo.ico"
+html_static_path = ['_static']
+html_css_files = ['custom.css']
+html_use_opensearch = 'https://www.mdanalysis.org/pmdacli'
 
 napoleon_use_ivar = True
 napoleon_use_rtype = False

docs/rst/index.rst

@@ -1,11 +1,13 @@
-========
-Contents
-========
+.. include:: ../../README.rst
+
+.. ========
+.. Contents
+.. ========
 
 .. toctree::
    :maxdepth: 2
+   :hidden:	      
 
-   readme
    installation
    philosophy
    usage
@@ -14,10 +16,4 @@ Contents
    changelog
    authors
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`