Initial move to MkDocs

.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)

.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 [email protected]
+      - 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

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

docs/api/index.md

@@ -0,0 +1,5 @@
+# `atomlib` API Reference
+
+Top-level exports:
+
+::: atomlib

docs/api/util.md

@@ -0,0 +1,2 @@
+
+::: atomlib.util