Add documentation

.gitlab-ci.yml

@@ -35,3 +35,13 @@ test:
     wheel_file=${wheels[0]}
     python -m pip install --group dev ${wheel_file}
     make test
+
+docs:
+  stage: test
+  script:
+    - python -m pip install --group docs .
+    - make docs
+  artifacts:
+    paths:
+      - docs/site/*
+    expire_in: 1 week

.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: '3.14'
+  jobs:
+    install:
+      - pip install --upgrade pip
+      - pip install --group 'docs'
+    build:
+      html:
+        - make docs
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp --recursive docs/site/* $READTHEDOCS_OUTPUT/html/

Makefile

@@ -1,6 +1,6 @@
 # Commands used by CI
 
-.PHONY: format lint build test
+.PHONY: format lint build test docs
 
 format:
 	ruff check --fix
@@ -17,3 +17,7 @@ build:
 test:
 	pytest
 	python -m doctest README.md
+
+docs:
+	python docs/make.py
+	zensical build -f docs/zensical.toml --clean

README.md

@@ -7,6 +7,7 @@
 [![Tests](https://github.com/ValkyrieSystems/jbpy/actions/workflows/test.yml/badge.svg)](https://github.com/ValkyrieSystems/jbpy/actions/workflows/test.yml)
 
 **jbpy** is a library for reading and writing Joint BIIF Profile files. Including:
+
 * National Imagery Transmission Format (NITF)
 * North Atlantic Treaty Organisation (NATO) Secondary Imagery Format (NSIF)
 

docs/.gitignore

@@ -0,0 +1,2 @@
+src/api/
+site/

docs/make.py

@@ -0,0 +1,26 @@
+import pathlib
+import shutil
+
+import pdoc
+import pdoc.render
+
+here = pathlib.Path(__file__).parent
+out = here / "src" / "api"
+if out.exists():
+    shutil.rmtree(out)
+
+# Render parts of pdoc's documentation into src/api...
+pdoc.render.configure(
+    docformat="numpy",
+    template_directory=here / "pdoc-template",
+)
+modules = [
+    "jbpy",
+    "jbpy.core",
+    "jbpy.image_data",
+]
+pdoc.pdoc(*modules, output_directory=out)
+
+# ...and rename the .html files to .md so that zensical picks them up!
+for f in out.glob("**/*.html"):
+    f.rename(f.with_suffix(".md"))

docs/pdoc-template/frame.html.jinja2

@@ -0,0 +1,20 @@
+---
+title: {{ module.modulename if module else "API Reference" }}
+---
+
+<div>
+    {% block content %}{% endblock %}
+
+    {% filter minify_css %}
+        {% block style %}
+            {#
+            The important part is that we leave out layout.css here.
+            Ideally we would still include Bootstrap Reboot, but that breaks mkdocs' theme.
+            <style>{% include "resources/bootstrap-reboot.min.css" %}</style>
+            #}
+            <style>{% include "syntax-highlighting.css" %}</style>
+            <style>{% include "theme.css" %}</style>
+            <style>{% include "content.css" %}</style>
+        {% endblock %}
+    {% endfilter %}
+</div>

docs/src/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/zensical.toml

@@ -0,0 +1,64 @@
+[project]
+site_name = "jbpy Documentation"
+site_description = "Documentation for jbpy: a library for reading and writing Joint BIIF Profile files."
+site_author = "Valkyrie Systems Corporation"
+#site_url = "https://www.example.com/"  TODO: set once hosted
+repo_name = "ValkyrieSystems/jbpy"
+repo_url = "https://github.com/ValkyrieSystems/jbpy"
+docs_dir = "src"
+use_directory_urls = false
+
+copyright = """
+Copyright © 2026, Valkyrie Systems Corporation
+"""
+
+nav = [
+    { "Get started" = "index.md"},
+    {"API Reference" = [
+        {"jbpy" = "api/jbpy.md"},
+        {"jbpy.core" = "api/jbpy/core.md"},
+        {"jbpy.image_data" = "api/jbpy/image_data.md"},
+    ]}
+]
+
+
+# ----------------------------------------------------------------------------
+# Section for configuring theme options
+# ----------------------------------------------------------------------------
+[project.theme]
+language = "en"
+logo = "https://raw.githubusercontent.com/ValkyrieSystems/sarkit/main/docs/source/_static/sarkit_logo.png"
+
+# Zensical provides a number of feature toggles that change the behavior
+# of the documentation site.
+features = [
+    "announce.dismiss",
+    "content.code.annotate",
+    "content.code.copy",
+    "content.code.select",
+    "content.footnote.tooltips",
+    "content.tabs.link",
+    "content.tooltips",
+    "navigation.footer",
+    "navigation.indexes",
+    "navigation.instant",
+    "navigation.instant.prefetch",
+    "navigation.path",
+    "navigation.sections",
+    "navigation.top",
+    "navigation.tracking",
+    "search.highlight",
+]
+
+[project.theme.icon]
+repo = "fontawesome/brands/github"
+
+[project.markdown_extensions.pymdownx.highlight]
+anchor_linenums = true
+line_spans = "__span"
+pygments_lang_class = true
+[project.markdown_extensions.pymdownx.inlinehilite]
+[project.markdown_extensions.pymdownx.snippets]
+[project.markdown_extensions.pymdownx.superfences]
+[project.markdown_extensions.admonition]
+[project.markdown_extensions.pymdownx.details]

pyproject.toml

@@ -63,6 +63,11 @@ examples = [
     "pillow",
 ]
 
+docs = [
+    "pdoc>=16.0.0",
+    "zensical>=0.0.18",
+]
+
 [project.urls]
 Repository = "https://github.com/ValkyrieSystems/jbpy"
 "Bug Tracker" = "https://github.com/ValkyrieSystems/jbpy/issues"