diff --git a/devtools/docs_requirements.txt b/devtools/docs_requirements.txt index 8a37d75..2b19af2 100644 --- a/devtools/docs_requirements.txt +++ b/devtools/docs_requirements.txt @@ -1,5 +1,6 @@ sphinx>=2.2 -sphinx-py3doc-enhanced-theme +sphinx-rtd-theme +sphinx-sitemap sphinx-argparse CommonMark mock diff --git a/docs/AUTHORS.rst b/docs/AUTHORS.rst index e531cb9..c62c7a1 100644 --- a/docs/AUTHORS.rst +++ b/docs/AUTHORS.rst @@ -3,3 +3,4 @@ Authors * Philip Loche (`github `_) * Joao M. C. Teixeira (`webpage `_, `github `_) +* Oliver Beckstein (`webpage `_, `github `_) diff --git a/docs/CHANGELOG.rst b/docs/CHANGELOG.rst index 7ed8987..31eb135 100644 --- a/docs/CHANGELOG.rst +++ b/docs/CHANGELOG.rst @@ -2,6 +2,11 @@ Changelog ========= +new_version +----------- + +* MDA-style documentation pages (#70) + v0.1.2 (2021-11-18) ------------------------------------------ diff --git a/docs/rst/_static/custom.css b/docs/rst/_static/custom.css new file mode 100644 index 0000000..c069992 --- /dev/null +++ b/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; +} diff --git a/docs/rst/_static/logos/AUTHOR b/docs/rst/_static/logos/AUTHOR new file mode 100644 index 0000000..9794ee3 --- /dev/null +++ b/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. + diff --git a/docs/rst/_static/logos/mdacli-logo-square.pdf b/docs/rst/_static/logos/mdacli-logo-square.pdf new file mode 100644 index 0000000..6b69b15 Binary files /dev/null and b/docs/rst/_static/logos/mdacli-logo-square.pdf differ diff --git a/docs/rst/_static/logos/mdacli-logo-square.png b/docs/rst/_static/logos/mdacli-logo-square.png new file mode 100644 index 0000000..2909e81 Binary files /dev/null and b/docs/rst/_static/logos/mdacli-logo-square.png differ diff --git a/docs/rst/_static/logos/mdacli-logo.pdf b/docs/rst/_static/logos/mdacli-logo.pdf new file mode 100644 index 0000000..4b5ebdf Binary files /dev/null and b/docs/rst/_static/logos/mdacli-logo.pdf differ diff --git a/docs/rst/_static/logos/mdacli-logo.png b/docs/rst/_static/logos/mdacli-logo.png new file mode 100644 index 0000000..7b30c44 Binary files /dev/null and b/docs/rst/_static/logos/mdacli-logo.png differ diff --git a/docs/rst/_static/logos/mdanalysis-logo.ico b/docs/rst/_static/logos/mdanalysis-logo.ico new file mode 100644 index 0000000..3c102d0 Binary files /dev/null and b/docs/rst/_static/logos/mdanalysis-logo.ico differ diff --git a/docs/rst/_templates/footer.html b/docs/rst/_templates/footer.html new file mode 100644 index 0000000..5fd6ad4 --- /dev/null +++ b/docs/rst/_templates/footer.html @@ -0,0 +1,11 @@ +{% extends "!footer.html" %} + +{% block extrafooter %} +{{ super() }} +

Please see + our Privacy Policy + to learn how MDAnalysis collects data.

+ +
+{% endblock %} diff --git a/docs/rst/conf.py b/docs/rst/conf.py index 246d68b..d5ac57a 100644 --- a/docs/rst/conf.py +++ b/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 diff --git a/docs/rst/index.rst b/docs/rst/index.rst index a3f16a8..317a503 100644 --- a/docs/rst/index.rst +++ b/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`