From 056353eedf8c787905c885d9b9df6cb6f854e7e2 Mon Sep 17 00:00:00 2001 From: Irfan Alibay Date: Mon, 4 Sep 2023 08:41:59 +0100 Subject: [PATCH] Try switching themes (#61) * Switch to mdanalysis-sphinx-theme * Fix old doc build errors and warnings --- docs/requirements.yaml | 4 +- docs/scripts/gen_mdakits.py | 2 +- docs/source/_static/custom.css | 225 -------------- docs/source/_static/readable.css | 463 ----------------------------- docs/source/_templates/footer.html | 11 - docs/source/conf.py | 33 +- docs/source/makingakit.rst | 6 +- utils/mdakit.py | 6 +- 8 files changed, 15 insertions(+), 735 deletions(-) delete mode 100644 docs/source/_static/custom.css delete mode 100644 docs/source/_static/readable.css delete mode 100644 docs/source/_templates/footer.html diff --git a/docs/requirements.yaml b/docs/requirements.yaml index a9d5a920..a3604287 100644 --- a/docs/requirements.yaml +++ b/docs/requirements.yaml @@ -7,8 +7,8 @@ dependencies: - python - pip - - sphinx==5.3.0 - - sphinx_rtd_theme + - sphinx + - mdanalysis-sphinx-theme - pyyaml - pydantic diff --git a/docs/scripts/gen_mdakits.py b/docs/scripts/gen_mdakits.py index 5b744672..f1df12df 100644 --- a/docs/scripts/gen_mdakits.py +++ b/docs/scripts/gen_mdakits.py @@ -71,7 +71,7 @@ def generate_mdakit_index(target='.', excludedirs=["template",]): " 2. Provide sufficient details to allow others to use and " "potentially participate in the development of the MDAKits\n" " 3. Provide information about the current state of the MDAKits " - "and how they interact with the latest versions of MDAnalysis\n" + "and how they interact with the latest versions of MDAnalysis\n\n" "Each of the MDAKits in the following table links to a page with " "more details about what the MDAKits do, how they can be " "installed and how to participate in their development.\n") diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css deleted file mode 100644 index de8d2e67..00000000 --- a/docs/source/_static/custom.css +++ /dev/null @@ -1,225 +0,0 @@ -/* override css for readable.css */ - -/* styles/fonts to match http://mdanalysis.org (see public/css) */ -/* MDAnalysis orange: #FF9200 */ -/* MDAnalysis gray: #808080 */ -/* MDAnalysis white: #FFFFFF */ -/* MDAnalysis black: #000000 */ -/* Very light orange: #FFEBD0 */ -/* Code orange: #ca6500 */ -/* 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; -} -/* override table width restrictions */ -@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; - } - } - -dl.footnote p { - font-weight: lighter; - font-size: 14px -} \ No newline at end of file diff --git a/docs/source/_static/readable.css b/docs/source/_static/readable.css deleted file mode 100644 index 1d170214..00000000 --- a/docs/source/_static/readable.css +++ /dev/null @@ -1,463 +0,0 @@ -/* - * Adapted for combining with alabaster for MDAnalysis. - * To be used as a custom CSS - * - * based on: - * - * readable.css_t - * ~~~~~~~~~~~~~~ - * - * Sphinx stylesheet -- readable theme. - * - * :copyright: Copyright 2013 by Ignacy Sokolowski. - * :license: MIT, see LICENSE for details. - * - */ - - -/* -- page layout --------------------------------------------------------- */ - -body { - font-family: 'Georgia', serif; - font-size: 17px; - margin: 0; - padding: 0; -} - -div.document { - margin: 10px auto 0 auto; - /* max-width: {{ page_width }}; */ -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - /* margin: 0 0 0 {{ theme_sidebarwidth|toint }}px; */ -} - -div.body { - background-color: #ffffff; - color: #3e4349; - padding: 0 30px 30px 30px; -} - -div.footer { - color: #555; - font-size: 14px; - margin: 20px auto 30px auto; - text-align: right; - max-width: 880px; -} - -div.footer a { - color: #444; - text-decoration: underline; -} - -div.related { - padding: 10px 10px; - width: auto; -} - -div.sphinxsidebar { - float: left; - font-size: 14px; - line-height: 1.5em; - margin-left: -100%; - /* width: {{ theme_sidebarwidth|toint }}px; */ -} - -div.sphinxsidebarwrapper { - font-size: 14px; - line-height: 1.5em; - padding: 10px 0 10px 10px; -} - -div.sphinxsidebar h3, -div.sphinxsidebar h4 { - color: #333; - font-size: 24px; - font-weight: normal; - margin: 0 0 5px 0; - padding: 0; -} - -div.sphinxsidebar h4 { - font-size: 1.1em; -} - -div.sphinxsidebar h3 a { - color: #333; -} - -div.sphinxsidebar p { - color: #888; -} - -div.sphinxsidebar p.searchtip { - line-height: 1.4em; -} - -div.sphinxsidebar ul { - color: #000; - margin: 10px 0 20px; - padding: 0; -} - -div.sphinxsidebar a { - color: #444; -} - -div.sphinxsidebar a:hover { - color: #d00; -} - -div.sphinxsidebar input { - border: 1px solid #ccc; - font-family: sans-serif; - font-size: 1em; -} - -/* -- body styles --------------------------------------------------------- */ - -a { - color: #900; - text-decoration: none; -} - -a:visited { - color: #700; -} - -a:hover { - color: #d00; - text-decoration: underline; -} - -hr { - border: 1px solid #b1b4b6; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { font-weight: normal; } - -div.body h1, -div.body h2, -div.body h3, -div.body h4 { color: #212224; } -div.body h5 { color: #000; } -div.body h6 { color: #777; } - -div.body h1 { margin: 0 0 10px 0; } -div.body h2, -div.body h3 { margin: 30px 0px 10px 0px; } -div.body h4, -div.body h5, -div.body h6 { margin: 20px 0px 10px 0px; } - -div.body h1 { padding: 0 0 10px 0; } -div.body h2, -div.body h3 { padding: 10px 0 10px 0; } -div.body h4 { padding: 10px 0 10px 0; } -div.body h5, -div.body h6 { padding: 10px 0 0 0; } - -div.body h1, -div.body h2, -div.body h3 { border-bottom: 1px solid #ddd; } -div.body h4 { border-bottom: 1px solid #e5e5e5; } - -div.body h1 { font-size: 230%; } -div.body h2 { font-size: 180%; } -div.body h3 { font-size: 130%; } -div.body h4 { font-size: 110%; } -div.body h5 { font-size: 105%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - background-color: #c60f0f; - color: #fff; -} - -div.body ul { - list-style: disc; - margin: 1em 0; - padding-left: 1.3em; -} - -div.body ul ul, div.body ol ul { - margin: .2em 0; - padding-left: 1.2em; -} - -div.body ul li { - padding: 2px 0; -} - -div.body ul.search li { - padding: 5px 0 5px 20px; -} - -div.body ol { - counter-reset: li; - margin-left: 0; - padding-left: 0; -} - -div.body ol ol { - margin: .2em 0; -} - -div.body ol > li { - list-style: none; - margin: 0 0 0 1.9em; - padding: 2px 1px; - position: relative; -} - -div.body ol > li:before { - content: counter(li) "."; - counter-increment: li; - top: -2px; - left: -1.9em; - width: 1.9em; - padding: 4px 0; - position: absolute; - text-align: left; -} - -div.body p, -div.body dd, -div.body li { - line-height: 1.4em; -} - -div.admonition p.admonition-title + p { - display: inline; -} - -div.highlight { - background-color: #fff; -} - -div.important, div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.attention, div.caution, div.hint, div.seealso, div.tip { - background-color: #fef9e9; - border: 1px solid #fbe091; -} - -div.topic { - background-color: #eee; -} - -div.danger, div.error, div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ':'; -} - -pre { - background-color: #f5f5f5; - border: 1px solid #C6C9CB; - color: #222; - font-size: 0.75em; - line-height: 1.5em; - margin: 1.5em 0 1.5em 0; - padding: 10px; - box-shadow: 1px 1px 1px #d8d8d8; - -webkit-box-shadow: 1px 1px 1px #d8d8d8; - -moz-box-shadow: 1px 1px 1px #d8d8d8; -} - -pre, tt, code { - font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; -} - -tt, code { - background-color: #ecf0f3; - font-size: 0.85em; -} - -tt.descname, code.descname { - font-size: 0.95em; -} - -tt.xref, a tt, code.xref, a code { - font-weight: normal; -} - -span.pre { - padding: 0 2px; -} - -dl.class, dl.function { - margin-bottom: 50px; -} - -dl.function > dt, -dl.attribute > dt, -dl.classmethod > dt, -dl.method > dt, -dl.class > dt, -dl.exception > dt { - background-color: #f5f5f5; - margin: 25px 0 10px 0; - padding: 1px 10px; -} - -table.docutils { - width: 100%; -} - -table.docutils.footnote { - width: auto; -} - -table.docutils thead, -table.docutils tfoot { - background: #f5f5f5; -} - -table.docutils thead tr th { - color: #000; - font-weight: normal; - padding: 7px 5px; - vertical-align: middle; -} - -table.docutils tbody tr th, -table.docutils tbody tr td { - border-bottom: 0; - border-top: solid 1px #ddd; - padding: 7px 5px; - vertical-align: top; -} -table.docutils tbody tr:last-child th, -table.docutils tbody tr:last-child td { - border-bottom: solid 1px #ddd; -} - -table.docutils thead tr td p, -table.docutils tfoot tr td p, -table.docutils tbody tr td p, -table.docutils thead tr td ul, -table.docutils tfoot tr td ul, -table.docutils tbody tr td ul, -table.docutils thead tr td ol, -table.docutils tfoot tr td ol, -table.docutils tbody tr td ol { - margin: 0 0 .5em; -} -table.docutils thead tr td p.last, -table.docutils tfoot tr td p.last, -table.docutils tbody tr td p.last, -table.docutils thead tr td ul.last, -table.docutils tfoot tr td ul.last, -table.docutils tbody tr td ul.last, -table.docutils thead tr td ol.last, -table.docutils tfoot tr td ol.last, -table.docutils tbody tr td ol.last { - margin-bottom: 0; -} - -.viewcode-back { - font-family: Arial, sans-serif; -} - -div.viewcode-block:target { - background-color: #fef9e9; - border-top: 1px solid #fbe091; - border-bottom: 1px solid #fbe091; -} - -@media screen and (max-width: 870px) { - - div.document { - width: auto; - margin: 0; - } - - div.documentwrapper { - float: none; - } - - div.bodywrapper { - margin: 0; - } - - div.body { - min-height: 0; - padding: 0 20px 30px 20px; - } - - div.footer { - background-color: #333; - color: #888; - margin: 0; - padding: 10px 20px 20px; - text-align: left; - width: auto; - } - - div.footer a { - color: #bbb; - } - - div.footer a:hover { - color: #fff; - } - - div.sphinxsidebar { - background-color: #333; - color: #fff; - float: none; - margin: 0; - padding: 10px 20px; - width: auto; - } - - div.sphinxsidebar h3, - div.sphinxsidebar h4, - div.sphinxsidebar p, - div.sphinxsidebar h3 a { - color: #fff; - } - - div.sphinxsidebar ul { - color: #999; - } - - div.sphinxsidebar a { - color: #aaa; - } - - div.sphinxsidebar a:hover { - color: #fff; - } - -} diff --git a/docs/source/_templates/footer.html b/docs/source/_templates/footer.html deleted file mode 100644 index 5fd6ad48..00000000 --- a/docs/source/_templates/footer.html +++ /dev/null @@ -1,11 +0,0 @@ -{% extends "!footer.html" %} - -{% block extrafooter %} -{{ super() }} -

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

- -
-{% endblock %} diff --git a/docs/source/conf.py b/docs/source/conf.py index bcdf6eec..7d0df881 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -96,29 +96,14 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' +html_theme = 'mdanalysis_sphinx_theme' # 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. -color = {'orange': '#FF9200', - 'gray': '#808080', - 'white': '#FFFFFF', - 'black': '#000000', } html_theme_options = { - 'canonical_url': '', - 'logo_only': True, - 'display_version': True, - 'prev_next_buttons_location': 'bottom', - 'style_external_links': False, - 'style_nav_header_background': 'white', # '#e76900', # dark orange - # Toc options - 'collapse_navigation': True, - 'sticky_navigation': True, - 'navigation_depth': 4, - 'includehidden': True, - 'titles_only': False, + 'mda_official': True, } # Add any paths that contain custom static files (such as style sheets) here, @@ -126,12 +111,11 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] html_css_files = [ - 'custom.css', - 'https://cdn.datatables.net/1.13.4/css/jquery.dataTables.min.css', + 'https://cdn.datatables.net/1.13.6/css/jquery.dataTables.min.css', ] html_js_files = [ - 'https://cdn.datatables.net/1.13.4/js/jquery.dataTables.min.js', + 'https://cdn.datatables.net/1.13.6/js/jquery.dataTables.min.js', 'main.js', ] @@ -214,12 +198,7 @@ # -- Extension configuration ------------------------------------------------- -rst_epilog = """ -.. |MDAKit_Registry_version| replace:: {0} -""".format(version) - - intersphinx_mapping = { - 'https://docs.python.org/3/': None, - 'https://docs.mdanalysis.org/stable/': None, + 'python': ('https://docs.python.org/3/', None), + 'mdanalysis': ('https://docs.mdanalysis.org/stable/', None), } diff --git a/docs/source/makingakit.rst b/docs/source/makingakit.rst index 301be466..cea3c303 100644 --- a/docs/source/makingakit.rst +++ b/docs/source/makingakit.rst @@ -358,7 +358,7 @@ After this point, two more requirements are satisfied: Providing documentation *********************** -The cookiecutter includes a `Read the Docs `_ +The cookiecutter includes a `Read the Docs `__ configuration as well a premade documentation environment file that is used by Read the Docs and for building locally. First, we need to install the correct environment for building the documentation. In the ``docs/`` directory, run: @@ -500,7 +500,7 @@ Refeshing the RMSF documentation will now show a properly formatted citation usi Deploying the documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Log into `Read the Docs `_ and navigate to the +Log into `Read the Docs `__ and navigate to the dashboard. Click the "Import a Project" button and find the repository in the list. Click the "+" and confirm that the name, URL, and default branch are correct. @@ -628,4 +628,4 @@ Apart from actively developing the kit, changes in kit dependencies, or even Pyt For this reason, the kits' continuous integration is rerun weekly to confirm the kits expected behavior. In the event that a kit no longer passes its tests, an issue in MDAnalysis/MDAKits is automatically raised while notifying the maintainers indicated in the `metadata.yaml` file. While the registry developers will be happy to help where possible, ultimately, the maintainers of the MDAKit are responsible for resolving such issues and ensuring that the tests pass. -The issue will automatically close after the next CI run if the tests pass again. \ No newline at end of file +The issue will automatically close after the next CI run if the tests pass again. diff --git a/utils/mdakit.py b/utils/mdakit.py index 7aa1c1dc..30932c25 100644 --- a/utils/mdakit.py +++ b/utils/mdakit.py @@ -386,9 +386,9 @@ def write_mdakit_page(self): urls = [] authors = self.gen_authors(urls) - title = ("************************\n" + title = ("************************************************\n" f"{name}\n" - "************************\n\n") + "************************************************\n\n") description = (f"| **Description:**\n" f"| *{self.metadata.description}*\n") @@ -453,7 +453,7 @@ def write_mdakit_page(self): ) if self.metadata.src_install is not None: installation_instructions += ( - f"The source code of {name} can be " + f"\nThe source code of {name} can be " "installed using the following:\n\n" ".. code-block:: bash\n\n" )