diff --git a/ChangeLog.rst b/ChangeLog.rst new file mode 100644 index 00000000..7e429929 --- /dev/null +++ b/ChangeLog.rst @@ -0,0 +1,10 @@ +Changelog +========= + +The format is based on `Keep a Changelog `__. +This project adheres to `Semantic Versioning `__. + +v0.x.x - 20xx-xx-xx + +Added +~~~~~ diff --git a/Credits.rst b/Credits.rst new file mode 100644 index 00000000..c1f8f372 --- /dev/null +++ b/Credits.rst @@ -0,0 +1,6 @@ +Credits +======= + +The following people have contributed to **parsnip**: + +* Jen Bradley, University of Michigan - *Creator and lead developer* diff --git a/README.md b/README.md deleted file mode 100644 index 8007f85b..00000000 --- a/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# parsnip -Minimal library for parsing CIF/mmCIF files in Python. diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..ad1424de --- /dev/null +++ b/README.rst @@ -0,0 +1,85 @@ +.. _header: + +.. image:: _static/parsnip_header_dark.svg + :width: 600 + :class: only-light + +.. image:: _static/parsnip_header_light.svg + :width: 600 + :class: only-dark + +.. + TODO: set up Readthedocs, PyPI, and conda-forge + +|ReadTheDocs| +|PyPI| +|conda-forge| + +.. |ReadTheDocs| image:: https://readthedocs.org/projects/parsnip-cif/badge/?version=latest + :target: http://parsnip-cif.readthedocs.io/en/latest/?badge=latest +.. |PyPI| image:: https://img.shields.io/pypi/v/parsnip-cif.svg + :target: https://pypi.org/project/parsnip-cif/ +.. |conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/parsnip-cif.svg + :target: https://anaconda.org/conda-forge/parsnip-cif + + +.. _introduction: + +**parsnip** is a minimal Python library for parsing `CIF `_ files. While its primary focus is on simplicity and portability, performance-oriented design choices are made where possible. + +The ``parsnip.parse`` module handles standard CIF files (including those under the `CIF 1.1 `_ and `CIF 2.0 `_ standards). It includes a table reader for `loop\_`-delimited tables as well as a key-value pair reader. Provide a filename and a list of keys to either of these functions and you're all set to read start parsing CIF files! + + +.. TODO: reintroduce this text when the parsemm module is updated + ``parsnip.parsemm`` handles `mmCIF ` files. + + +.. _installing: + +Setup +----- + +**parsnip** may be installed with **pip** or from **conda-forge**. + + +Installation via pip +^^^^^^^^^^^^^^^^^^^^ + +.. code:: bash + + python -m pip install parsnip + +Installation via conda-forge +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: bash + + conda install -c conda-forge parsnip + + +Installation from source +^^^^^^^^^^^^^^^^^^^^^^^^ + +First, clone the repository: + +.. code:: bash + + git clone https://github.com/glotzerlab/parsnip.git + cd parsnip + +Then, choose one of the following. While **parsnip** is only dependent on Numpy, +additional dependencies are required to run the tests and build the docs. + +.. code:: bash + + pip install . # Install with no additional dependencies + pip install .[tests] # Install with dependencies required to run tests + pip install .[tests,doc] # Install with dependencies required to run tests and make docs + +Dependencies +^^^^^^^^^^^^ + +.. literalinclude:: ../../requirements.txt + :language: text + +.. _contributing: diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 00000000..dc1312ab --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..b0389e2a --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,4 @@ +autodocsumm +furo +numpy>=1.19 +sphinx diff --git a/doc/source/_static/parsnip_header_dark.svg b/doc/source/_static/parsnip_header_dark.svg new file mode 100644 index 00000000..5df0e5e8 --- /dev/null +++ b/doc/source/_static/parsnip_header_dark.svg @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/source/_static/parsnip_header_light.svg b/doc/source/_static/parsnip_header_light.svg new file mode 100644 index 00000000..fb14a75f --- /dev/null +++ b/doc/source/_static/parsnip_header_light.svg @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/source/_static/parsnip_logo_favicon.svg b/doc/source/_static/parsnip_logo_favicon.svg new file mode 100644 index 00000000..8d8516bd --- /dev/null +++ b/doc/source/_static/parsnip_logo_favicon.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/doc/source/_static/umich-block-M.svg b/doc/source/_static/umich-block-M.svg new file mode 100644 index 00000000..f656a215 --- /dev/null +++ b/doc/source/_static/umich-block-M.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + diff --git a/doc/source/_templates/page.html b/doc/source/_templates/page.html new file mode 100644 index 00000000..e284003a --- /dev/null +++ b/doc/source/_templates/page.html @@ -0,0 +1,71 @@ +{% extends "furo/page.html" %} +{% block footer %} + +
+
+

Development of {{ project }} is led by the Glotzer Group at the University of Michigan. +

+ + {%- if show_copyright %} + + {%- endif %} + {% trans %}Made with {% endtrans -%} + {%- if show_sphinx -%} + {% trans %}Sphinx and {% endtrans -%} + @pradyunsg's + {% endif -%} + {% trans %} + Furo + {% endtrans %} + {%- if last_updated -%} +
+ {% trans last_updated=last_updated|e -%} + Last updated on {{ last_updated }} + {%- endtrans -%} +
+ {%- endif %} +
+ +
+{% endblock footer %} diff --git a/doc/source/changelog.rst b/doc/source/changelog.rst new file mode 100644 index 00000000..63b44cb2 --- /dev/null +++ b/doc/source/changelog.rst @@ -0,0 +1 @@ +.. include:: ../../changelog.rst diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..1f847292 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,61 @@ +"""Configuration file for the Sphinx documentation builder.""" + +import datetime + +CURRENT_YEAR = datetime.date.today().year +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "parsnip" +copyright = f"2024-{ CURRENT_YEAR } The Regents of the University of Michigan" +author = "Jen Bradley" +release = "0.1.0" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "autodocsumm", +] + +templates_path = ["_templates"] +exclude_patterns = ["build", "Thumbs.db", ".DS_Store"] +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "numpy": ("https://numpy.org/doc/stable/", None), +} + +autodoc_default_options = { + "inherited-members": True, + "show-inheritance": True, + "autosummary": True, +} + +pygments_style = "friendly" +pygments_dark_style = "native" + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +html_static_path = ["_static"] +html_theme_options = { + "sidebar_hide_name": True, + "light_logo": "parsnip_header_dark.svg", + "dark_logo": "parsnip_header_light.svg", + "dark_css_variables": { + "color-brand-primary": "#5187b2", + "color-brand-content": "#5187b2", + }, + "light_css_variables": { + "color-brand-primary": "#406a8c", + "color-brand-content": "#406a8c", + }, +} +html_favicon = "_static/parsnip_logo_favicon.svg" diff --git a/doc/source/credits.rst b/doc/source/credits.rst new file mode 100644 index 00000000..0a22c266 --- /dev/null +++ b/doc/source/credits.rst @@ -0,0 +1 @@ +.. include:: ../../credits.rst diff --git a/doc/source/development.rst b/doc/source/development.rst new file mode 100644 index 00000000..d693fa1c --- /dev/null +++ b/doc/source/development.rst @@ -0,0 +1,89 @@ +.. _development: + +================= +Development Guide +================= + + +All contributions to **parsnip** are welcome! +Developers are invited to contribute to the framework by pull request to the package repository on `GitHub`_, and all users are welcome to provide contributions in the form of **user feedback** and **bug reports**. +We recommend discussing new features in form of a proposal on the issue tracker for the appropriate project prior to development. + +.. _github: https://github.com/glotzerlab/parsnip + +General Guidelines +================== + +All code contributed to **parsnip** must adhere to the following guidelines: + + * Use a two branch model of development: + + - Most new features and bug fixes should be developed in branches based on ``main``. + - API incompatible changes and those that significantly change existing functionality should be based on ``breaking`` + * Hard dependencies (those that end users must install to use **parsnip**) are *strongly* discouraged, and should be avoided where possible. Numpy is the sole exception to this, as it is already included in most scientific computing software stacks. + * Additional dependencies required by developers (those used to run tests or build docs) are undesirable but allowed. + * All code should adhere to the source code conventions and satisfy the documentation and testing requirements discussed below. + +As portability is a primary feature of **parsnip**, tests are run run on Python versions 3.9 and later. However, first class support should only be expected for versions covered by `NEP 29`_. + +.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html + + +Style Guidelines +---------------- + +The **parsnip** package adheres to a reasonably strict set of style guidelines. +All code in **parsnip** should be formatted using `ruff`_ via pre-commit. This provides an easy workflow to enforce a number of style and syntax rules that have been configured for the project. + +.. tip:: + + `pre-commit`_ has been configured to run a number of linting and formatting tools. It is recommended to set up pre-commit to run automatically: + + .. code-block:: bash + + python -m pip install pre-commit + pre-commit install # Set up git hook scripts + + Alternatively, the tools can be run manually with the following command: + + .. code-block:: bash + + git add .; pre-commit run + +.. _ruff: https://docs.astral.sh/ruff/ +.. _pre-commit: https://pre-commit.com/ + + +Documentation +------------- + +API documentation should be written as part of the docstrings of the package in the `Google style `__. + +Docstrings are automatically validated using `pydocstyle `_ whenever the ruff pre-commit hooks are run. +The `official documentation `_ is generated from the docstrings using `Sphinx `_. + +In addition to API documentation, inline comments are strongly encouraged. +Code should be written as transparently as possible, so the primary goal of documentation should be explaining the algorithms or mathematical concepts underlying the code. +Avoid comments that simply restate the nature of lines of code: for example, the comment "set up regex pattern" is uninformative, since the code itself should make this obvious, *e.g*, ``re.compile(r"^(_\w+)\s+(\d+)")``. +On the other hand, the comment "read an underscore-prefixed word and a numeric value seperated by whitespace" is instructive. +Multiline comments for regex strings may sometimes be necessary. + +Building Documentation +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + cd doc + make clean + make html + open build/html/index.html + + +Unit Tests +---------- + +All code should include a set of tests which test for correct behavior. +All tests should be placed in the ``tests`` folder at the root of the project. +In general, most parts of parsnip primarily require `unit tests `_, but where appropriate `integration tests `_ are also welcome. Core functions should be tested against the sample CIF files included in ``tests/sample_data``. +Tests in **parsnip** use the `pytest `__ testing framework. +To run the tests, simply execute ``pytest`` at the root of the repository. diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..a3b928cf --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,36 @@ +.. include:: ../../README.rst + + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + + introduction + installation + quickstart + + +.. toctree:: + :maxdepth: 2 + :caption: API + + package-parse + + +.. toctree:: + :maxdepth: 1 + :caption: Reference + + genindex + development + changelog + credits + license + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 00000000..48be32e4 --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,8 @@ +.. _installation: + +Installation +=================== + +.. include:: ../../README.rst + :start-after: .. _installing: + :end-before: .. _contributing: diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst new file mode 100644 index 00000000..bb0083a6 --- /dev/null +++ b/doc/source/introduction.rst @@ -0,0 +1,6 @@ +Introduction +=================== + +.. include:: ../../README.rst + :start-after: .. _introduction: + :end-before: .. _installing: diff --git a/doc/source/license.rst b/doc/source/license.rst new file mode 100644 index 00000000..6bead3b1 --- /dev/null +++ b/doc/source/license.rst @@ -0,0 +1,5 @@ +License +======= + +.. literalinclude:: ../../LICENSE + :language: none diff --git a/doc/source/package-parse.rst b/doc/source/package-parse.rst new file mode 100644 index 00000000..203fb440 --- /dev/null +++ b/doc/source/package-parse.rst @@ -0,0 +1,8 @@ +Parse Module +============================== + +.. rubric:: Overview + +.. automodule:: parsnip.parse + :members: + :show-inheritance: diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst new file mode 100644 index 00000000..7fc80ea1 --- /dev/null +++ b/doc/source/quickstart.rst @@ -0,0 +1,4 @@ +.. _quickstart: + +Quickstart Tutorial +=================== diff --git a/pyproject.toml b/pyproject.toml index 28ab86b2..00df5b6f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "parsnip" -version = "0.0.2" +version = "0.1.0" requires-python = ">=3.9" # This could be updated to a minimum of 3.6 description = "Minimal library for parsing CIF/mmCIF files in Python." readme = "README.md"