Skip to content

Automate Sphinx documentation build and deployment #56

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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