mdanalysis / mdanalysis-sphinx-theme

The official MDAnalysis Sphinx documentation theme.

MDAnalysis Repository README

MDAnalysis is a Python library for the analysis of computer simulations of many-body systems at the molecular scale, spanning use cases from interactions of drugs with proteins to novel materials. It is widely used in the scientific community and is written by scientists for scientists.

It works with a wide range of popular simulation packages including Gromacs, Amber, NAMD, CHARMM, DL_Poly, HooMD, LAMMPS and many others — see the lists of supported trajectory formats and topology formats. MDAnalysis also includes widely used analysis algorithms in the MDAnalysis.analysis module.

The MDAnalysis project uses an open governance model and is fiscally sponsored by NumFOCUS. Consider making a tax-deductible donation to help the project pay for developer time, professional services, travel, workshops, and a variety of other needs.

This project is bound by a Code of Conduct.

If you use MDAnalysis in your project consider letting your users and the world know about it by displaying the MDAnalysis badge! Embedding code is available for different markups.

Example analysis script

import MDAnalysis as mda

# Load simulation results with a single line
u = mda.Universe('topol.tpr','traj.trr')

# Select atoms
ag = u.select_atoms('name OH')

# Atom data made available as Numpy arrays
ag.positions
ag.velocities
ag.forces

# Iterate through trajectories
for ts in u.trajectory:
    print(ag.center_of_mass())

Documentation

New users should read the Quickstart Guide and might want to look at our videos, in which core developers explain various aspects of MDAnalysis.

All users should read the User Guide.

Developers may also want to refer to the MDAnalysis API docs.

A growing number of tutorials are available that explain how to conduct RMSD calculations, structural alignment, distance and contact analysis, and many more.

Installation and availability

The latest release can be installed via pip or conda as described in the Installation Quick Start.

Source code is hosted in a git repository at https://github.com/MDAnalysis/mdanalysis and is packaged under the GNU General Public License, version 3 or any later version. Invidiual source code components are provided under a mixture of GPLv3+ compatible licenses, including LGPLv2.1+ and GPLv2+. Please see the file LICENSE for more information.

Contributing

Please report bugs or enhancement requests through the Issue Tracker. Questions can also be asked on GitHub Discussions.

If you are a new developer who would like to start contributing to MDAnalysis get in touch on GitHub Discussions. To set up a development environment and run the test suite read the developer guide.

Citation

When using MDAnalysis in published work, please cite the following two papers:

• R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler, D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein. MDAnalysis: A Python package for the rapid analysis of molecular dynamics simulations. In S. Benthall and S. Rostrup, editors, Proceedings of the 15th Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy. doi: 10.25080/Majora-629e541a-00e
• N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein. MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. J. Comput. Chem. 32 (2011), 2319--2327. doi: 10.1002/jcc.21787

For citations of included algorithms and sub-modules please see the references.

mdanalysis-sphinx-theme's Issues

Document how to work with sphinxcontrib-bibtex

I think appropriate guidelines would be:

• for an internal module where you think a table may get rendered through autosummary, use footbibliography, the directive for local bibs
• for an overall references page for the entire module: use bibliography. The issue in #25 was that a table got incorrectly rendered after the correctly rendered bibliography, so as long as we take care not to use global references in a module, I think we will avoid it in the future.
  For reference, the user guide has a global bibliography: https://userguide.mdanalysis.org/stable/references.html

Also we should pin to bibtex>2.0 where the footbib was first introduced

Add mechanism to view multiple options

It would be handy to be able to view multiple options (e.g. mda_official True or False, looking at both the user guide and MDA core docs).

Version is incorrect

Version is 1.2.x, probably inherited from msmb_theme -- this should get fixed. Also, versioneer has probably been updated in the past 8 years.

Allow favicon override for official repos; also, have nothing to start with

In the unlikely event that we want a specific favicon, this issue is analogous to #34 .

Also, IMO, we should allow for no favicon and that should even be the default (although definitely open to discussion!). We can set the cookiecutter to do the placeholder as an example for how to change it. However, the way it's currently set up, there's no way to do no favicon, since the check uses tobool.

Add authors to docs

This repo has authors that should show up in the footer of the docs, like our other repos.

Fix long description markup

ERROR    `long_description` has syntax errors in markup and would not be        
         rendered on PyPI.  

https://github.com/MDAnalysis/mdanalysis-sphinx-theme/actions/runs/6073286511/job/16474913626

Docs are incorrect

The documentation explaining customisation and other parts of the sphinx theme were written for the OpenFF Sphinx Theme and as such are inaccurate. This should get updated for easier maintainability.

Unpin sphinx upper version?

There's no issues currently raised anywhere to document this - can we just unpin the upper sphinx version?

Add AUTHORS

We should add the meta docs (authors, link to code of conduct, etc.) that the rest of our repositories have

Include logo details in license

This is one where I'm not 100% sure, but because we are copying the logo from one place to another as part of the wheel building process, I think we have to include the logo details in the license shipped in this repo. Or at least it would be "safer" to do so.

Diagnose and fix submodule inclusion in pypi deployment

https://github.com/MDAnalysis/mdanalysis-sphinx-theme/actions/runs/6069258433/job/16463404447

Package discovery isn't explicitly finding all sub-folders

See:

        ********************************************************************************
        ############################
        # Package would be ignored #
        ############################
        Python recognizes 'mdanalysis_sphinx_theme.sass' as an importable package[^1],
        but it is absent from setuptools' `packages` configuration.

        This leads to an ambiguous overall configuration. If you want to distribute this
        package, please make sure that 'mdanalysis_sphinx_theme.sass' is explicitly added
        to the `packages` configuration field.

        Alternatively, you can also rely on setuptools' discovery methods
        (for example by using `find_namespace_packages(...)`/`find_namespace:`
        instead of `find_packages(...)`/`find:`).

        You can read more about "package discovery" on setuptools documentation page:

        - https://setuptools.pypa.io/en/latest/userguide/package_discovery.html

        If you don't want 'mdanalysis_sphinx_theme.sass' to be distributed and are
        already explicitly excluding 'mdanalysis_sphinx_theme.sass' via
        `find_namespace_packages(...)/find_namespace` or `find_packages(...)/find`,
        you can try to use `exclude_package_data`, or `include-package-data=False` in
        combination with a more fine grained `package-data` configuration.

        You can read more about "package data files" on setuptools documentation page:

        - https://setuptools.pypa.io/en/latest/userguide/datafiles.html


        [^1]: For Python, any directory (with suitable naming) can be imported,
              even if it does not contain any `.py` files.
              On the other hand, currently there is no concept of package data
              directory, all directories are treated like packages.
        ********************************************************************************

Amongst other warnings on build.

logo and favicon are not rendered properly on subpages

When viewing pages deeper than the index page, the logo and favicon cannot be found. The resource requested is in _static/ when it should be something like ../_static/, depending on depth.

CI deployment not working in all PRs

It may depend on who opens the PR?
Example: #22

Incompatible with `sphinxcontrib-bibtex`?

When trying to use bibtex through the sphinxcontrib-bibtex extension, the previously rendered functions table failed to render.

For reference, here is a capture of a working version

It appears that the div containing the table (<div class="wy-table-responsive"><table class="autosummary longtable docutils align-default">...) is outside of the main content.

I see that in the example documentation for this repo that citations are included directly in the docstrings.

New bugfix release w/ sphinx 7 support

The last release pinned to <7 which prevents py3.12 builds from working, see: MDAnalysis/pytng#109

A new release will be necessary, ideally after #72 since the secrets have now been deleted.

Update changelog

Changelog no longer reflects the current set of changes made / release status.

Allow logo override for official repos

Many official repos (e.g. mdacli, user guide) have specific logos that we want to use instead of the normal mda logo. Currently the logic overrides this if mda_official is True.

pypi-deployment action has the wrong name

https://github.com/MDAnalysis/mdanalysis-sphinx-theme/actions/runs/6004510417

No bullets in list items

Expected behavior

We should see bullets in unordered lists.

Actual behavior

For some reason in this one specific scenario, an unordered list in the class docstring, neither MDA Sphinx theme nor the original sphinx theme has bullets: MDAnalysis/mdanalysis#4359

I reckon we could just update the theme to always have bullets in these lists.

Initial release plan

@lilyminium, can we plan for an initial release? I would like to begin using this project in my MDAKits ASAP using a pip install. For now I can use the git+ prefix, but want to move to PyPI hosted package sooner rather than later.

Unpin sphinx when sphinx_rtd_theme updates

The 2.0 release should support 7.

Missing navigation menu on mobile website?

Describe the bug
It seems that the navigation menu is no longer accessible in the mobile version of the UserGuide.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://userguide.mdanalysis.org/stable/index.html using a mobile device

Expected behavior
I expect to be able to access the navigation menu on mobile too, so that I can navigate the UserGuide.

Actual behavior
There is no navigation menu as far as I can tell, and therefore I have to rely on Google to land on the correct UserGuide page.

Smartphone (please complete the following information):

• Device: iPhone SE
• OS: iOS16
• Browser: Safari/Firefox

Automatic PyPI package deployment on new release

Can we make PyPI package deployments automatic with releases?

Provide a project description and other niceties

We should get our metadata up to standard:

https://pypi.org/project/mdanalysis-sphinx-theme/0.1.1/

Black navbar

Ugh:

Probably related to #61, #60

Re-implement navbar links

Is your feature request related to a problem?

We have these html_sidebars options that point to navigation.html, which used to exist with the old alabaster theme but do not with sphinx_rtd_theme. Having these would be helpful to use with the extra_nav_links option to, e.g., link to MDAKits registries.

Start using MDA theme in official repos

I expect this to require changes to the theme -- opened #32.

Repos:

• core: https://github.com/lilyminium/mdanalysis/tree/switch-docs-theme
• user guide: https://github.com/MDAnalysis/UserGuide/tree/switch-docs-theme
• mdakits registry
• mdakit cookiecutter MDAnalysis/cookiecutter-mdakit#85
• mdacli: https://github.com/MDAnalysis/mdacli/tree/switch-docs-theme
• transport-analysis
• solvation-analysis
• griddataformats: https://github.com/MDAnalysis/GridDataFormats/tree/switch-docs-theme
• hole2-mdakit
• distopia MDAnalysis/distopia#146
• pytng MDAnalysis/pytng#109
• membrane-curvature MDAnalysis/membrane-curvature#122
• mdanalysisdata
• pmda

Are table width examples correct?

Maybe I don't understand how sphinx widths work, but if we look here; https://www.mdanalysis.org/mdanalysis-sphinx-theme/PR32/additional_samples.html#list-tables

It seems like the 50% width table is larger than alleged 100% width table, is this correct?