coherent.docs 1.0.0__tar.gz

coherent_docs-1.0.0/(meta)/entry_points.txt

@@ -0,0 +1,2 @@
+[pipx.run]
+coherent.docs = coherent.docs.core:run

coherent_docs-1.0.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

coherent_docs-1.0.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: coherent.docs
+Version: 1.0.0
+Author-Email: Jason R. Coombs <jaraco@jaraco.com>
+Summary: API and narrative docs builder for the /coherent-oss/system
+Requires-Python: >= 3.8
+Requires-Dist: coherent.build
+Requires-Dist: pip-run
+Requires-Dist: sphinx>=3.5
+Requires-Dist: jaraco.packaging>=9.3
+Requires-Dist: rst.linker>=1.9
+Requires-Dist: furo
+Requires-Dist: sphinx-lint
+Provides-Extra: test
+Provides-Extra: doc
+Project-URL: Source, https://github.com/coherent-oss/coherent.docs
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+License-Expression: MIT
+
+[![](https://img.shields.io/pypi/v/coherent.docs)](https://pypi.org/project/coherent.docs)
+
+![](https://img.shields.io/pypi/pyversions/coherent.docs)
+
+[![](https://github.com/coherent-oss/coherent.docs/actions/workflows/main.yml/badge.svg)](https://github.com/coherent-oss/coherent.docs/actions?query=workflow%3A%22tests%22)
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+[![Coherent Software Development System](https://img.shields.io/badge/coherent%20system-informational)](https://github.com/coherent-oss/system)
+

coherent_docs-1.0.0/README.md

@@ -0,0 +1,10 @@
+[![](https://img.shields.io/pypi/v/coherent.docs)](https://pypi.org/project/coherent.docs)
+
+![](https://img.shields.io/pypi/pyversions/coherent.docs)
+
+[![](https://github.com/coherent-oss/coherent.docs/actions/workflows/main.yml/badge.svg)](https://github.com/coherent-oss/coherent.docs/actions?query=workflow%3A%22tests%22)
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+[![Coherent Software Development System](https://img.shields.io/badge/coherent%20system-informational)](https://github.com/coherent-oss/system)
+

coherent_docs-1.0.0/coherent/docs/__init__.py

@@ -0,0 +1,16 @@
+"""
+Tool for orchestrating documentation builds using Sphinx.
+
+>>> __name__
+'coherent.docs'
+"""
+
+__requires__ = [
+    'coherent.build',
+    'pip-run',
+    'sphinx >= 3.5',
+    'jaraco.packaging >= 9.3',
+    'rst.linker >= 1.9',
+    'furo',
+    'sphinx-lint',
+]

coherent_docs-1.0.0/coherent/docs/__main__.py

@@ -0,0 +1,3 @@
+from . import core
+
+__name__ == '__main__' and core.run()

coherent_docs-1.0.0/coherent/docs/conf.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'jaraco.packaging.sphinx',
+]
+
+master_doc = "index"
+html_theme = "furo"
+
+# Be strict about any broken references
+nitpicky = True
+nitpick_ignore: list[tuple[str, str]] = []
+
+# Include Python intersphinx mapping to prevent failures
+# jaraco/skeleton#51
+extensions += ['sphinx.ext.intersphinx']
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}
+
+# Preserve authored syntax for defaults
+autodoc_preserve_defaults = True
+
+# Add support for linking usernames, PyPI projects, Wikipedia pages
+github_url = 'https://github.com/'
+extlinks = {
+    'user': (f'{github_url}%s', '@%s'),
+    'pypi': ('https://pypi.org/project/%s', '%s'),
+    'wiki': ('https://wikipedia.org/wiki/%s', '%s'),
+}
+extensions += ['sphinx.ext.extlinks']
+
+# local

coherent_docs-1.0.0/coherent/docs/core.py

@@ -0,0 +1,132 @@
+import contextlib
+import importlib.resources
+import os
+import pathlib
+import re
+import subprocess
+import sys
+
+import pip_run.deps
+import pip_run.launch
+from coherent.build import bootstrap, discovery
+
+AUTOMODULE_TMPL = """\
+
+.. automodule:: {mod}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+"""
+
+
+def find_modules(package_name: str, root: pathlib.Path = pathlib.Path()) -> list[str]:
+    """
+    Find all public modules in the package using the essential layout.
+
+    >>> find_modules('my.pkg', pathlib.Path('/nonexistent'))
+    []
+    """
+
+    def to_module(path):
+        parts = path.relative_to(root).with_suffix('').parts
+        if parts[-1] == '__init__':
+            parts = parts[:-1]
+        return '.'.join((package_name,) + parts) if parts else package_name
+
+    return sorted(
+        filter(
+            lambda m: not re.search(r'\._', m),
+            map(to_module, root.rglob('*.py')),
+        ),
+        key=lambda m: (m.count('.'), m),
+    )
+
+
+def make_modules_rst(modules: list[str]) -> str:
+    """
+    Generate the automodule directives for each public module.
+    """
+    return ''.join(AUTOMODULE_TMPL.format(mod=m) for m in modules)
+
+
+def make_index_rst(package_name: str, modules: list[str]) -> str:
+    """
+    Generate ``index.rst`` content from the template plus
+    ``automodule`` directives for each public module.
+    """
+    template = (
+        importlib.resources
+        .files(__package__)
+        .joinpath('index.tmpl.rst')
+        .read_text('utf-8')
+    )
+    return template.format(modules=make_modules_rst(modules))
+
+
+def build_env(target, *, orig=os.environ):
+    """
+    Build the environment for invoking sphinx, inserting the installed
+    packages path onto PYTHONPATH.
+
+    # TODO: consolidate with coherent.test and other similar helpers.
+    >>> env = build_env('foo', orig=dict(PYTHONPATH='bar'))
+    >>> env['PYTHONPATH'].replace(os.pathsep, ':')
+    'foo:bar'
+    """
+    overlay = dict(
+        PYTHONPATH=pip_run.launch._path_insert(
+            orig.get('PYTHONPATH', ''), os.fspath(target)
+        ),
+        PYTHONSAFEPATH='1',
+    )
+    return {**orig, **overlay}
+
+
+def load_conf_py():
+    return importlib.resources.files(__package__).joinpath('conf.py').read_text('utf-8')
+
+
+@contextlib.contextmanager
+def configure_docs(package_name: str):
+    """
+    Create the ``docs/`` directory and generate ``conf.py`` and ``index.rst``
+    (only if they do not already exist), yielding for the sphinx build, then
+    cleaning up any files we created.
+    """
+    docs = pathlib.Path('docs')
+    docs.mkdir(exist_ok=True)
+    modules = find_modules(package_name)
+    with (
+        bootstrap.assured(docs / 'conf.py', load_conf_py),
+        bootstrap.assured(
+            docs / 'index.rst', lambda: make_index_rst(package_name, modules)
+        ),
+    ):
+        yield
+
+
+@contextlib.contextmanager
+def project_on_path():
+    """
+    Install the target project plus doc build dependencies in an ephemeral
+    environment and yield the installation home path.
+    """
+    deps = pip_run.deps.load('--editable', '.[doc]')
+    with bootstrap.write_pyproject(), deps as home:
+        yield home
+
+
+def run():
+    package_name = discovery.best_name()
+    with project_on_path() as home:
+        with configure_docs(package_name):
+            cmd = [
+                sys.executable,
+                '-m',
+                'sphinx',
+                '-b',
+                'html',
+                'docs',
+                'build/html',
+            ]
+            raise SystemExit(subprocess.call(cmd, env=build_env(home)))

coherent_docs-1.0.0/coherent/docs/index.tmpl.rst

@@ -0,0 +1,19 @@
+Welcome to |project| documentation!
+===================================
+
+.. sidebar-links::
+   :home:
+   :pypi:
+   :releases:
+
+.. toctree::
+   :maxdepth: 1
+
+{modules}
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

coherent_docs-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["flit-core >=3.11, <4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "coherent.docs"
+version = "1.0.0"
+description = "API and narrative docs builder for the /coherent-oss/system"
+readme = "README.md"
+requires-python = ">= 3.8"
+dependencies = ["coherent.build", "pip-run", "sphinx>=3.5", "jaraco.packaging>=9.3", "rst.linker>=1.9", "furo", "sphinx-lint"]
+classifiers = ["Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only"]
+license = "MIT"
+
+[[project.authors]]
+name = "Jason R. Coombs"
+email = "jaraco@jaraco.com"
+
+[project.urls]
+Source = "https://github.com/coherent-oss/coherent.docs"
+
+[project.entry-points."pipx.run"]
+"coherent.docs" = "coherent.docs.core:run"
+
+[project.scripts]