Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MDA-style docs #70

Merged
merged 11 commits into from
Nov 24, 2021
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion devtools/docs_requirements.txt
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
sphinx>=2.2
sphinx-py3doc-enhanced-theme
sphinx-rtd-theme
sphinx-sitemap
sphinx-argparse
CommonMark
mock
Binary file added docs/rst/_static/.DS_Store
Binary file not shown.
206 changes: 206 additions & 0 deletions docs/rst/_static/custom.css
Original file line number Diff line number Diff line change
@@ -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;
}
16 changes: 16 additions & 0 deletions docs/rst/_static/logos/AUTHOR
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
The MDAnalysis 'Atom' logo was created by Christian Beckstein and is

Copyright (c) 2011 Christian Beckstein

MDAnalysis Logo 'Atom' by Christian Beckstein is licensed 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 logo is contained in the file 'mdanalysis-logo.png'.

Derivatives in the files 'mdanalysis-logo-127x55.png',
'mdanalysis-logo-200x150.png', 'mdanalysis-logo.ico' were created for
inclusion in MDAnalysis and on websites related to MDAnalysis. They
are distributed under the same license as the 'Atom' logo.
Binary file added docs/rst/_static/logos/mdacli-logo.pdf
Binary file not shown.
Binary file added docs/rst/_static/logos/mdacli-logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/rst/_static/logos/mdanalysis-logo.ico
Binary file not shown.
11 changes: 11 additions & 0 deletions docs/rst/_templates/footer.html
Original file line number Diff line number Diff line change
@@ -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>
Comment on lines +8 to +9
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that this part is necessary for analytics.

The number of page accesses is actually an important number for us to demonstrate impact so we do want to keep track of which pages are seen. This is fully anonymous, though.

</div>
{% endblock %}
40 changes: 30 additions & 10 deletions docs/rst/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
import mock
import sys

import sphinx_py3doc_enhanced_theme
import sphinx_rtd_theme


# activate if there are dependencies
Expand All @@ -15,6 +15,8 @@
'MDAnalysis',
'MDAnalysis.analysis',
'MDAnalysis.analysis.base',
'MDAnalysis.transformations',
'MDAnalysis.transformations.boxdimensions',
'numpy',
]

Expand All @@ -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/"
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in preparation for #71


todo_include_todos = True

exclude_patterns = [
Expand All @@ -57,7 +64,8 @@
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
Expand All @@ -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
Expand Down
16 changes: 6 additions & 10 deletions docs/rst/index.rst
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
========
Contents
========
.. include:: ../../README.rst

.. ========
.. Contents
.. ========

.. toctree::
:maxdepth: 2
:hidden:

readme
installation
philosophy
usage
Expand All @@ -14,10 +16,4 @@ Contents
changelog
authors

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`