Skip to content

api-documentation.md

Latest commit

 

History

History
71 lines (56 loc) · 3.59 KB

api-documentation.md

File metadata and controls

71 lines (56 loc) · 3.59 KB
Raw

Building and publishing the API reference

The API reference is generated from src/IntaRNA/*.h and doc/doxygen/mainpage.md. Its HTML header, footer, and extra stylesheet live in doc/doxygen/; the common configuration is doc/doxygen.cfg.

Local HTML build

Install Doxygen and Graphviz (on Ubuntu: sudo apt-get install doxygen graphviz). The HTML templates are based on Doxygen 1.9.8, the version provided by the Ubuntu 24.04 CI runner. When updating Doxygen, compare them with freshly generated templates (doxygen -w html header.html footer.html default.css) and verify navigation and search before publishing.

From the repository root:

bash doc/build-api.sh
python3 doc/check-api.py doxygen-doc/html

Open doxygen-doc/html/index.html, or serve the directory with python3 -m http.server --directory doxygen-doc/html and browse http://localhost:8000/. An optional output directory can be passed to the build script; relative paths are resolved from the calling directory. The script only builds HTML and does not require a compiler, Boost, ViennaRNA, or an IntaRNA build. It uses the package version from configure.ac.

In a configured Autotools checkout, the existing make doxygen-doc target uses the same content and styling. Configure with --disable-doxygen-pdf for an HTML-only build; PDF generation additionally requires the configured LaTeX tools.

The link check verifies the entry page's local links (including class/member anchors), its styles and scripts, and the class/namespace/search entry points. Review Doxygen's warnings as well: existing header documentation can emit warnings, so the workflow does not treat every legacy documentation warning as fatal. New unresolved references should be fixed before merging.

GitHub Pages

.github/workflows/documentation.yml is a reusable documentation build, called by build-wasm.yml for pull requests and pushes to master; it can also be run manually to inspect documentation artifacts. The documentation build uploads intarna-documentation, with the README-based Jekyll guide and Doxygen output under api/.

build-wasm.yml combines that artifact with the tested browser interface under gui/ and publishes one Pages artifact. This preserves the existing guide and API; two independent publishers would overwrite each other's site. Only a push or manual dispatch on BackofenLab/IntaRNA's master can deploy. Pull requests and forks cannot publish. The deployment job alone receives Pages and OIDC write permissions, and deployments share one concurrency group.

Pages configuration

The repository already uses Settings → Pages → Build and deployment → Source → GitHub Actions. For another repository, select that source before deploying, and deliberately adjust the deployment repository guard. Run the WebAssembly and web interface workflow on master or push a subsequent commit. Retain any required approval rules on the github-pages environment. This PR does not change live publishing settings. See GitHub's custom Pages workflow documentation.

No generated HTML, access token, or separate documentation branch is committed. The intarna-pages-preview artifact contains the combined site for PR review. See the browser deployment notes for the complete build and validation sequence.