Skip to content

📝 Add the Sphinx API docs setup the Deploy APIs workflow needs - #20

Merged
kammce merged 1 commit into
mainfrom
api-docs
Oct 26, 2026
Merged

kammce merged 1 commit into
mainfrom
api-docs

Conversation

@kammce

@kammce kammce commented Oct 26, 2026

Copy link
Copy Markdown
Member

Fixes the 📚 Deploy APIs workflow, which has failed on every push and release since the repo was created.

The shared api_docs_gen.yml workflow installs docs/requirements.txt and then runs conan hal docs, which runs Doxygen and then Sphinx in docs/. scatter_span had no requirements.txt and no Sphinx conf.py, so the job stopped at the install step.

Changes

  • docs/conf.py, docs/requirements.txt, docs/_static/ and docs/_templates/: copied unchanged from strong_ptr. async_context has identical copies.
  • docs/doxygen.conf: replaced the full default Doxyfile with the short config strong_ptr and async_context use. That config emits the XML Sphinx reads (the old one emitted HTML and LaTeX only) and names the project scatter_span instead of scatter span. conf.py builds the version switcher URL from that name: https://libhal.github.io/api/scatter_span/switcher.json.
  • docs/index.rst and docs/api/: pages for scatter_span and its iterator, scatter_array and spanable, and for_each_run().
  • .cspell.json: adds the doxygenclass, doxygenconcept and doxygenfunction directive names.

Testing

  • conan hal docs --doc_version main ./docs builds locally with the pinned requirements (Sphinx 8.1.3).
  • Every page renders its API.
  • Doxygen still warns about members that aren't documented yet, as before. Those warnings don't fail the build.

The shared api_docs_gen workflow installs docs/requirements.txt and runs
conan hal docs, which builds docs/conf.py from Doxygen XML. scatter_span
had neither, so the job failed on every push and release.

The files match strong_ptr and async_context. doxygen.conf is their short
config, which emits XML and names the project scatter_span, the name the
docs URL uses.

@kammce kammce left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lgtm

@kammce
kammce merged commit c7da1ee into main Oct 26, 2026
9 checks passed
@kammce
kammce deleted the api-docs branch October 26, 2026 12:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant