diff --git a/.github/scripts/get_versioninfo.py b/.github/scripts/get_versioninfo.py new file mode 100644 index 0000000..a0fa6b6 --- /dev/null +++ b/.github/scripts/get_versioninfo.py @@ -0,0 +1,17 @@ +#!/usr/bin/env python3 + +import os, sys +from build.util import project_wheel_metadata + +if 'GITHUB_OUTPUT' in os.environ: + file = open(os.environ['GITHUB_OUTPUT'], 'w') +else: + file = sys.stdout + +msg = project_wheel_metadata('.') +version = msg.get('version') +project = msg.get('name') + +print(f'project={project}', file=file) +print(f'version={version}', file=file) +print(f'tag=v{version}', file=file) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 839b141..e5c3990 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -6,44 +6,36 @@ on: workflow_dispatch: permissions: - contents: read - pages: write - id-token: write + contents: write concurrency: group: "pages" cancel-in-progress: true jobs: - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - + docs: runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v3 + - uses: actions/checkout@v3 - name: Install python uses: actions/setup-python@v4 with: - python-version: 3.11 + python-version: '3.11' cache: 'pip' - cache-dependency-path: setup.cfg + cache-dependency-path: pyproject.toml - name: Install dependencies run: | - python -m pip install --upgrade pip + python -m pip install --upgrade pip setuptools build pip install -e '.[docs]' - - name: Build documentation + - name: Get version + id: version + # outputs project, version, and tag + run: python .github/scripts/get_versioninfo.py + - name: Set git user run: | - sphinx-build docs _build - - name: Setup GitHub Pages - uses: actions/configure-pages@v3 - - name: Upload Artifact - uses: actions/upload-pages-artifact@v1 - with: - path: '_build/' + git config user.name github-actions + git config user.email github-actions@github.com + - name: Fetch gh-pages branch + run: git fetch origin gh-pages --depth=1 - name: Deploy - id: deployment - uses: actions/deploy-pages@v1 - + run: mike deploy -u '${{ steps.version.outputs.version }}' dev --push diff --git a/atomlib/util.py b/atomlib/util.py index fd5bf49..4a99862 100644 --- a/atomlib/util.py +++ b/atomlib/util.py @@ -22,15 +22,15 @@ def map_some(f: t.Callable[[T], U], val: t.Optional[T]) -> t.Optional[U]: """ - Map ``f`` over ``val`` if not ``None``. + Map `f` over `val` if not `None`. """ return None if val is None else f(val) FileOrPath = t.Union[str, Path, TextIOBase, t.TextIO] -"""Open text file or path to a file. Use with :func:`open_file`.""" +"""Open text file or path to a file. Use with [open_file][atomlib.util.open_file].""" BinaryFileOrPath = t.Union[str, Path, t.TextIO, t.BinaryIO, IOBase] -"""Open binary file or path to a file. Use with :func:`open_file_binary`.""" +"""Open binary file or path to a file. Use with [open_file_binary][atomlib.util.open_file_binary].""" def _validate_file(f: t.Union[t.IO, IOBase], mode: t.Union[t.Literal['r'], t.Literal['w']]): @@ -98,7 +98,7 @@ def open_file_binary(f: BinaryFileOrPath, def localtime() -> datetime.datetime: - """Return the current time in a timezone-aware datetime object.""" + """Return the current time in a timezone-aware [datetime][datetime.datetime] object.""" ltime = time.localtime() tz = datetime.timezone(datetime.timedelta(seconds=ltime.tm_gmtoff), ltime.tm_zone) return datetime.datetime.now(tz) @@ -126,9 +126,15 @@ def __get__(self, obj: t.Optional[T], ty: t.Optional[t.Type[T]] = None) -> t.Cal ) -def proc_seed(seed: object, entropy: object) -> t.Optional[NDArray[numpy.uint32]]: +def proc_seed(seed: t.Optional[object], entropy: object) -> t.Optional[NDArray[numpy.uint32]]: """ - Process a random seed for passing to ``numpy.random.default_rng``. + Process a random seed, which can be any object (or `None` for a random seed). + Return it in a form which can be passed to [numpy.random.default_rng][]. + + Uses a SHA-256 sum under the hood. + + `entropy` should be a routine-specific object, to ensure that separate random + routines called using the same seed return uncorrelated results. """ if seed is None: return None diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index ed88099..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# 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 = . -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/docs/api.rst b/docs/api.rst deleted file mode 100644 index 4fbf6a2..0000000 --- a/docs/api.rst +++ /dev/null @@ -1,24 +0,0 @@ -API Reference -============= - -Modules -------- - -.. currentmodule:: atomlib - -.. autosummary:: - :toctree: atomlib - - io - make - visualize - disloc - atoms - cell - atomcell - elem - transform - vec - bbox - types - util diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..9a7517e --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,5 @@ +# `atomlib` API Reference + +Top-level exports: + +::: atomlib diff --git a/docs/api/util.md b/docs/api/util.md new file mode 100644 index 0000000..bd343e4 --- /dev/null +++ b/docs/api/util.md @@ -0,0 +1,2 @@ + +::: atomlib.util diff --git a/docs/atomlib/atomlib.atomcell.rst b/docs/atomlib/atomlib.atomcell.rst deleted file mode 100644 index 82d6ed4..0000000 --- a/docs/atomlib/atomlib.atomcell.rst +++ /dev/null @@ -1,23 +0,0 @@ -atomlib.atomcell -================ -.. currentmodule:: atomlib.atomcell -.. automodule:: atomlib.atomcell - - - - -.. rubric:: Classes - -.. autoclass:: AtomCell - :members: - :undoc-members: - :private-members: -.. autoclass:: HasAtomCell - :members: - :undoc-members: - :private-members: -.. autoclass:: OrthoCell - :members: - :undoc-members: - :private-members: - diff --git a/docs/atomlib/atomlib.atoms.rst b/docs/atomlib/atomlib.atoms.rst deleted file mode 100644 index 4b4627c..0000000 --- a/docs/atomlib/atomlib.atoms.rst +++ /dev/null @@ -1,24 +0,0 @@ -atomlib.atoms -============= -.. currentmodule:: atomlib.atoms -.. automodule:: atomlib.atoms - - - -.. rubric:: Attributes - -.. autodata:: IntoAtoms -.. autodata:: AtomSelection -.. autodata:: AtomValues - -.. rubric:: Classes - -.. autoclass:: Atoms - :members: - :undoc-members: - :private-members: -.. autoclass:: HasAtoms - :members: - :undoc-members: - :private-members: - diff --git a/docs/atomlib/atomlib.bbox.rst b/docs/atomlib/atomlib.bbox.rst deleted file mode 100644 index 2395b51..0000000 --- a/docs/atomlib/atomlib.bbox.rst +++ /dev/null @@ -1,15 +0,0 @@ -atomlib.bbox -============ -.. currentmodule:: atomlib.bbox -.. automodule:: atomlib.bbox - - - - -.. rubric:: Classes - -.. autoclass:: BBox3D - :members: - :undoc-members: - :private-members: - diff --git a/docs/atomlib/atomlib.cell.rst b/docs/atomlib/atomlib.cell.rst deleted file mode 100644 index 86cb569..0000000 --- a/docs/atomlib/atomlib.cell.rst +++ /dev/null @@ -1,36 +0,0 @@ -atomlib.cell -============ -.. currentmodule:: atomlib.cell -.. automodule:: atomlib.cell - -.. rubric:: Function Summary -.. autosummary:: - - cell_to_ortho - ortho_to_cell - plane_to_zone - zone_to_plane - - -.. rubric:: Attributes - -.. autodata:: CoordinateFrame - -.. rubric:: Classes - -.. autoclass:: Cell - :members: - :undoc-members: - :private-members: -.. autoclass:: HasCell - :members: - :undoc-members: - :private-members: - - -.. rubric:: Functions - -.. autofunction:: cell_to_ortho -.. autofunction:: ortho_to_cell -.. autofunction:: plane_to_zone -.. autofunction:: zone_to_plane \ No newline at end of file diff --git a/docs/atomlib/atomlib.disloc.rst b/docs/atomlib/atomlib.disloc.rst deleted file mode 100644 index 6e03157..0000000 --- a/docs/atomlib/atomlib.disloc.rst +++ /dev/null @@ -1,27 +0,0 @@ -atomlib.disloc -============== -.. currentmodule:: atomlib.disloc -.. automodule:: atomlib.disloc - -.. rubric:: Function Summary -.. autosummary:: - - disloc_edge - disloc_loop_z - disloc_poly_z - disloc_screw - disloc_square_z - ellip_pi - - - - - -.. rubric:: Functions - -.. autofunction:: disloc_edge -.. autofunction:: disloc_loop_z -.. autofunction:: disloc_poly_z -.. autofunction:: disloc_screw -.. autofunction:: disloc_square_z -.. autofunction:: ellip_pi \ No newline at end of file diff --git a/docs/atomlib/atomlib.elem.rst b/docs/atomlib/atomlib.elem.rst deleted file mode 100644 index bb14523..0000000 --- a/docs/atomlib/atomlib.elem.rst +++ /dev/null @@ -1,27 +0,0 @@ -atomlib.elem -============ -.. currentmodule:: atomlib.elem -.. automodule:: atomlib.elem - -.. rubric:: Function Summary -.. autosummary:: - - get_elem - get_elems - get_ionic_radius - get_mass - get_radius - get_sym - - - - - -.. rubric:: Functions - -.. autofunction:: get_elem -.. autofunction:: get_elems -.. autofunction:: get_ionic_radius -.. autofunction:: get_mass -.. autofunction:: get_radius -.. autofunction:: get_sym \ No newline at end of file diff --git a/docs/atomlib/atomlib.io.rst b/docs/atomlib/atomlib.io.rst deleted file mode 100644 index 5e985f4..0000000 --- a/docs/atomlib/atomlib.io.rst +++ /dev/null @@ -1,33 +0,0 @@ -atomlib.io -========== -.. currentmodule:: atomlib.io -.. automodule:: atomlib.io - -.. rubric:: Function Summary -.. autosummary:: - - read - read_cfg - read_cif - read_xsf - read_xyz - write - write_cfg - write_xsf - write_xyz - - - - - -.. rubric:: Functions - -.. autofunction:: read -.. autofunction:: read_cfg -.. autofunction:: read_cif -.. autofunction:: read_xsf -.. autofunction:: read_xyz -.. autofunction:: write -.. autofunction:: write_cfg -.. autofunction:: write_xsf -.. autofunction:: write_xyz \ No newline at end of file diff --git a/docs/atomlib/atomlib.make.rst b/docs/atomlib/atomlib.make.rst deleted file mode 100644 index ca46fe3..0000000 --- a/docs/atomlib/atomlib.make.rst +++ /dev/null @@ -1,33 +0,0 @@ -atomlib.make -============ -.. currentmodule:: atomlib.make -.. automodule:: atomlib.make - -.. rubric:: Function Summary -.. autosummary:: - - cesium_chloride - diamond - fcc - fluorite - graphite - perovskite - slab - wurtzite - zincblende - - - - - -.. rubric:: Functions - -.. autofunction:: cesium_chloride -.. autofunction:: diamond -.. autofunction:: fcc -.. autofunction:: fluorite -.. autofunction:: graphite -.. autofunction:: perovskite -.. autofunction:: slab -.. autofunction:: wurtzite -.. autofunction:: zincblende \ No newline at end of file diff --git a/docs/atomlib/atomlib.transform.rst b/docs/atomlib/atomlib.transform.rst deleted file mode 100644 index 167efb2..0000000 --- a/docs/atomlib/atomlib.transform.rst +++ /dev/null @@ -1,27 +0,0 @@ -atomlib.transform -================= -.. currentmodule:: atomlib.transform -.. automodule:: atomlib.transform - - - - -.. rubric:: Classes - -.. autoclass:: AffineTransform3D - :members: - :undoc-members: - :private-members: -.. autoclass:: FuncTransform3D - :members: - :undoc-members: - :private-members: -.. autoclass:: LinearTransform3D - :members: - :undoc-members: - :private-members: -.. autoclass:: Transform3D - :members: - :undoc-members: - :private-members: - diff --git a/docs/atomlib/atomlib.types.rst b/docs/atomlib/atomlib.types.rst deleted file mode 100644 index 4306207..0000000 --- a/docs/atomlib/atomlib.types.rst +++ /dev/null @@ -1,23 +0,0 @@ -atomlib.types -============= -.. currentmodule:: atomlib.types -.. automodule:: atomlib.types - -.. rubric:: Function Summary -.. autosummary:: - - to_vec3 - - -.. rubric:: Attributes - -.. autodata:: VecLike -.. autodata:: Pts3DLike -.. autodata:: Num -.. autodata:: ElemLike - - - -.. rubric:: Functions - -.. autofunction:: to_vec3 \ No newline at end of file diff --git a/docs/atomlib/atomlib.util.rst b/docs/atomlib/atomlib.util.rst deleted file mode 100644 index 9f3e97a..0000000 --- a/docs/atomlib/atomlib.util.rst +++ /dev/null @@ -1,33 +0,0 @@ -atomlib.util -============ -.. currentmodule:: atomlib.util -.. automodule:: atomlib.util - -.. rubric:: Function Summary -.. autosummary:: - - localtime - map_some - open_file - open_file_binary - - -.. rubric:: Attributes - -.. autodata:: FileOrPath -.. autodata:: BinaryFileOrPath - -.. rubric:: Classes - -.. autoclass:: opt_classmethod - :members: - :undoc-members: - :private-members: - - -.. rubric:: Functions - -.. autofunction:: localtime -.. autofunction:: map_some -.. autofunction:: open_file -.. autofunction:: open_file_binary \ No newline at end of file diff --git a/docs/atomlib/atomlib.vec.rst b/docs/atomlib/atomlib.vec.rst deleted file mode 100644 index 34f467c..0000000 --- a/docs/atomlib/atomlib.vec.rst +++ /dev/null @@ -1,43 +0,0 @@ -atomlib.vec -=========== -.. currentmodule:: atomlib.vec -.. automodule:: atomlib.vec - -.. rubric:: Function Summary -.. autosummary:: - - dot - in_polygon - is_diagonal - miller_3_to_4_plane - miller_3_to_4_vec - miller_4_to_3_plane - miller_4_to_3_vec - norm - para - perp - polygon_solid_angle - polygon_winding - reduce_vec - split_arr - - - - - -.. rubric:: Functions - -.. autofunction:: dot -.. autofunction:: in_polygon -.. autofunction:: is_diagonal -.. autofunction:: miller_3_to_4_plane -.. autofunction:: miller_3_to_4_vec -.. autofunction:: miller_4_to_3_plane -.. autofunction:: miller_4_to_3_vec -.. autofunction:: norm -.. autofunction:: para -.. autofunction:: perp -.. autofunction:: polygon_solid_angle -.. autofunction:: polygon_winding -.. autofunction:: reduce_vec -.. autofunction:: split_arr \ No newline at end of file diff --git a/docs/atomlib/atomlib.visualize.rst b/docs/atomlib/atomlib.visualize.rst deleted file mode 100644 index 527583b..0000000 --- a/docs/atomlib/atomlib.visualize.rst +++ /dev/null @@ -1,39 +0,0 @@ -atomlib.visualize -================= -.. currentmodule:: atomlib.visualize -.. automodule:: atomlib.visualize - -.. rubric:: Function Summary -.. autosummary:: - - get_azim_elev - get_elem_color - get_zone - show_atoms_2d - show_atoms_3d - show_atoms_mpl_2d - show_atoms_mpl_3d - - - -.. rubric:: Classes - -.. autoclass:: AtomImage - :members: - :undoc-members: - :private-members: -.. autoclass:: AtomImageMpl - :members: - :undoc-members: - :private-members: - - -.. rubric:: Functions - -.. autofunction:: get_azim_elev -.. autofunction:: get_elem_color -.. autofunction:: get_zone -.. autofunction:: show_atoms_2d -.. autofunction:: show_atoms_3d -.. autofunction:: show_atoms_mpl_2d -.. autofunction:: show_atoms_mpl_3d \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 7a4f337..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,82 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# 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 = 'atomlib' -#copyright = '' -author = 'Colin Gilgenbach' -release = '0.1' - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -nitpicky = True -nitpick_ignore = [ - ('py:class', 'type'), - ('py:class', 'T'), - ('py:class', 'U'), - ('py:class', 'P'), - ('py:class', 'U_co'), -] - -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', - 'sphinx.ext.mathjax', -] - -intersphinx_mapping = { - 'python': ('https://docs.python.org/3/', None), - 'numpy': ('https://numpy.org/doc/stable/', None), - 'matplotlib': ('https://matplotlib.org/stable/', None), - 'h5py': ('https://docs.h5py.org/en/latest/', None), - 'scipy': ('https://docs.scipy.org/doc/scipy/', None), - 'pyarrow': ('https://arrow.apache.org/docs/', None), - 'polars': ('https://pola-rs.github.io/polars/py-polars/html/', None), - 'h5py': ('https://docs.h5py.org/en/latest/', None), -} - -autodoc_default_options = { - 'member-order': 'bysource', -} - -autodoc_type_aliases = { - 'ArrayLike': 'numpy.typing.ArrayLike', - 'NDArray': 'numpy.typing.NDArray', - - 'Vec3': 'atomlib.types.Vec3', - 'VecLike': 'atomlib.types.VecLike', - 'Pts3DLike': 'atomlib.types.Pts3DLike', - 'Num': 'atomlib.types.Num', - 'ElemLike': 'atomlib.types.ElemLike', - - 'SchemaDict': 'atomlib.atoms.SchemaDict', - 'IntoAtoms': 'atomlib.atoms.IntoAtoms', - 'AtomSelection': 'atomlib.atoms.AtomSelection', - 'AtomValues': 'atomlib.atoms.AtomValues', - - 'CoordinateFrame': 'atomlib.cell.CoordinateFrame', - 'IntoTransform3D': 'atomlib.transform.IntoTransform3D', - 'CellType': 'atomlib.make.CellType', -} - -autodoc_typehints_format = 'short' - -templates_path = ['templates'] -exclude_patterns = [] - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = 'sphinx_rtd_theme' -#html_static_path = ['static'] - - -def setup(app): - ... - diff --git a/docs/examples.rst b/docs/examples.rst deleted file mode 100644 index bac945d..0000000 --- a/docs/examples.rst +++ /dev/null @@ -1,2 +0,0 @@ -Examples -======== diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index b7f1a2f..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -atomlib Documentation -=================================== - -atomlib is a collection of utilities for creating, -manipulating, and visualizing atomic structures. - -Contents -======== - -.. toctree:: - :maxdepth: 2 - - api.rst - install.rst - examples.rst - - -Index -===== - -* :ref:`genindex` diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 10d037b..0000000 --- a/docs/install.rst +++ /dev/null @@ -1,4 +0,0 @@ -Installation -============ - - diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index dc1312a..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@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/docs/style.css b/docs/style.css new file mode 100644 index 0000000..e69de29 diff --git a/docs/templates/autosummary/module.rst b/docs/templates/autosummary/module.rst deleted file mode 100644 index 6213d1d..0000000 --- a/docs/templates/autosummary/module.rst +++ /dev/null @@ -1,41 +0,0 @@ -{{ fullname | escape | underline}} -.. currentmodule:: {{ fullname }} -.. automodule:: {{ fullname }} -{% block functions %}{% if functions %} -.. rubric:: {{ _('Function Summary') }} -.. autosummary:: -{% for item in functions %} - {{ item }} -{%- endfor %}{% endif %}{% endblock %} -{% block modules %}{% if modules %} -.. rubric:: {{ _('Sub-modules') }} -.. autosummary:: - :toctree: - :recursive: -{% endif %}{% endblock %} -{% if attributes %} -.. rubric:: {{ _('Attributes') }} -{% for item in attributes %} -.. autodata:: {{ item }} -{%- endfor %}{% endif %} -{% if classes %} -.. rubric:: {{ _('Classes') }} -{% for item in classes %} -.. autoclass:: {{ item }} - :members: - :undoc-members: - :private-members: -{%- endfor %}{% endif %} -{% if exceptions %} -.. rubric:: {{ _('Exceptions') }} -{% for item in exceptions %} -.. autoclass:: {{ item }} - :members: - :undoc-members: - :private-members: -{%- endfor %}{% endif %} -{% if functions %} -.. rubric:: {{ _('Functions') }} -{% for item in functions %} -.. autofunction:: {{ item }} -{%- endfor %}{% endif %} diff --git a/docs/using/coords.md b/docs/using/coords.md new file mode 100644 index 0000000..9248114 --- /dev/null +++ b/docs/using/coords.md @@ -0,0 +1,4 @@ + +# Coordinate systems + +Under construction \ No newline at end of file diff --git a/docs/using/getting_started.md b/docs/using/getting_started.md new file mode 100644 index 0000000..f181c1b --- /dev/null +++ b/docs/using/getting_started.md @@ -0,0 +1,3 @@ + +`atomlib` is a package for creating, modifying, and controlling atomic structures. +It focuses on flexibilty, correctness, and the preservation of structure metadata, while still managing to support a wide variety of file formats. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..f0898a0 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,71 @@ +site_name: atomlib Documentation +repo_url: https://github.com/hexane360/atomlib + +docs_dir: 'docs' +site_dir: 'site' +extra_css: + - style.css + +nav: + - Home: index.md + - 'Using atomlib': + - Getting started: using/getting_started.md + - Coordinate systems: using/coords.md + - API: + - api/index.md + - atomlib.util: api/util.md + +theme: + name: material + palette: + primary: purple + accent: green + features: + - navigation.tabs + - navigation.tabs.sticky + - navigation.expand + - navigation.indexes +extra: + version: + provider: mike + +markdown_extensions: + - admonition + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + +plugins: + - search + - autorefs + - mkdocstrings: + custom_templates: templates + handlers: + python: + paths: [.] + import: + # 3rd-party object inventories + - https://docs.python.org/3/objects.inv + - https://numpy.org/doc/stable/objects.inv + - https://docs.scipy.org/doc/scipy/objects.inv + - https://matplotlib.org/stable/objects.inv + - https://docs.h5py.org/en/latest/objects.inv + - https://arrow.apache.org/docs/objects.inv + - https://pola-rs.github.io/polars/py-polars/html/objects.inv + options: + show_if_no_docstring: true + show_root_heading: true + members_order: source + filters: ["!^_", "!^__(all|repr|str)__$", "!^[TUKVP](_co(ntra)?)?$"] + inherited_members: true + - mike: + version_selector: true + canonical_version: latest + #alias_type: symlink + +watch: + - atomlib/ diff --git a/pyproject.toml b/pyproject.toml index 1767a78..17fbc1b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -46,8 +46,10 @@ dev = [ "nbmake>=1.4.1", ] docs = [ - "sphinx~=6.0", - "sphinx-rtd-theme~=1.0", + "mkdocs>=1.5.2", + "mkdocs-material==9.1.21", + "mkdocstrings[python]==0.22.0", + "mike==1.1.2", ] [project.urls]