Skip to content

Automate Sphinx documentation build and deployment #56

@TAJD

Description

@TAJD

Summary

The hosted documentation at https://marinlauber.github.io/Python-VPP/ is served from pre-built HTML committed to the docs/ folder on master. This HTML was last generated in 2020 and only documents VPPMod (4 methods).

Since then, comprehensive NumPy-style docstrings have been added to all source modules (see PR #55):

  • SailModSail, Main, Jib, Kite (including the I, J, LPG, HBI parameters requested in Add documentation on parameters to the documentation #53)
  • YachtModYacht, Keel, Rudder, Bulb, Appendage
  • AeroModAeroMod.__init__, update(), plus typo fixes
  • HydroModHydroMod.__init__, update(), _cf(), plus typo fixes
  • VPPMod — already had partial docs

The Sphinx source (sphinx/index.rst + new sphinx/modules.rst) has been updated to autodoc all 6 modules. The docs build cleanly with sphinx-build.

Problem

None of these improvements are visible on the live site because the docs/ HTML hasn't been rebuilt.

Proposal

Replace the manual build-and-commit workflow with a GitHub Actions workflow that:

  1. Builds Sphinx HTML on every push to master
  2. Deploys to GitHub Pages via actions/deploy-pages
  3. Removes the need to commit built HTML to the repo

This would:

  • Keep docs always in sync with code
  • Eliminate the stale docs/ folder from the repo
  • Make documentation a first-class part of the CI pipeline

Happy to implement this if you're interested — it's a ~20 line workflow file plus switching the GitHub Pages source from master:/docs to the GitHub Actions deployment.

Related: #53, #24

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions