Skip to content

docs(manual): doc generator and drift checks, the chapter template, and the setup-environment chapter #189

Description

@quantecon-services

PR 2 of the user manual (#178). The design is settled in #178, decisions 3 and 5; this issue is the unit of work.

  • scripts/generate-docs.py (Python 3 + PyYAML):
    • generates each chapter's Inputs and Outputs tables, each signpost README, and the action table in docs/user/README.md, between <!-- BEGIN GENERATED: … --> / <!-- END GENERATED --> markers;
    • --check prints the diff and fails.
  • PyYAML pinned in a requirements file, with a pip entry in .github/dependabot.yml.
  • actionlint installed as a pinned release with a checksum. It checks templates/*.yml and every complete workflow in a yaml block under docs/user.
  • Input checks: every quantecon/actions/<x>@… step in the docs and templates uses only inputs that exist and supplies every required one. Every complete example has a permissions: block.
  • All checks run in the harness gate job, beside the template pin-drift check from fix(actions): #107 correctness batch and #109 code items #173.
  • The chapter template.
  • docs/user/actions/setup-environment.md and its generated signpost README.

Done when the checks pass in the gate and the setup-environment chapter is merged.

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

    documentationRepo docs and contributor meta

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions