cascode-labs / build-sphinx-action Goto Github PK

Problem Statement

We have several projects that have Sphinx documentation. We would like to have those docs easily built for each release.

Proposed Solution

This action should build the sphinx documentation in the project's documentation folder. Its structure should be modelled after build-conda-action.

• check that the necessary components are available to build the docs. It should skip building the docs if something is missing but still exit successfully with a descriptive warning.
• Setup a conda env to build the docs. This should be defined from a env yml file, "envs/build-docs.yml"
• run the "${{ inputs.docs_path}/setup_source.sh" script before building the docs
• Build the docs by running the make file
• Upload the docs as an artifact.

Alternatives Considered

Proposed Action Plan

• 1. Create the action that meets the requirements above
• 2. Add a test workflow with each test case as a job
  • Test on a GitHub-hosted runner
  • Test a skipped run without a docs folder
  • Each test case should check that the artifact was uploaded.
• 3. Add a ReadMe modelled after the build-conda-action readme
  • Both readmes are based on the template Best-README-Template
• 4. Create a release to post it on the marketplacce.

Problem Statement

Some of our smaller projects only need a short set of documentation. A README file should be sufficient, but not everyone has access to our GitHub account to access it. It would be nice to be able to easily convert the readme file into a simple one page html site.

Proposed Solution

If the sphinx docs folder doesn't exist, then the action should create a simple one based on a simple conf.py contained in the action. It should run the quickstart and then copy over the readme and basic conf.py to generate the docs.

Alternatives Considered

• Create a seperate action for this function
• Create a simple docs folder for each project

Proposed Action Plan

• 1. Update the action
• 2 ...

Problem Statement

We'd like to easily publish to GitHub pages.

Proposed Solution

Include the option to release to GitHub pages. There are several different ways to do this but we can document the supported method and how to set up your repo settings to be compatible.

Alternatives Considered

Proposed Action Plan

• 1. we'll do this
• 2. We'll do that
• 3. Then we'll add tests for this and that.

Description

The action assumes the Sphinx output directory is the default (build). Setting it to something different in the Makefile within the docs directory or in the Action environment results in a warning. In my case, I have it set to _build.

Warning: No files were found with the provided path: docs/build/html. No artifacts will be uploaded.

To Reproduce

Steps to reproduce the behavior:

1. Adjust Sphinx Makefile with custom BUILDDIR
2. Run workflow
3. Warning is printed, output is not saved

build succeeded, 107 warnings.
The HTML pages are in _build/html.
Run actions/upload-artifact@v2
Warning: No files were found with the provided path: docs/build/html. No artifacts will be uploaded.

Expected behavior

The Makefile variable should be read.

Additional context

Add any other context about the problem here.

Problem Statement

I'd like to be able to control the conda environment name used for the build environment

Proposed Solution

Add an input, conda_build_env_name, to specify the environment name. It will still use the same default name if this input is left as the default.

Alternatives Considered

Previously it always set it to ${repo_name}-build-docs

Proposed Action Plan

• 1. Add the "conda_build_env_name" iput
• 2. Update the action to use the additional input
• 3. Update readme documentation

Problem Statement

We would like to decrease the time it takes to build the documentation.

Proposed Solution

We can reduce the time it takes to update or create the Conda build environment by using Mamba instead of the regular conda when mamba is available.

Alternatives Considered

If need to further improve the build speed we could:

1. We could also find a way to cache the environment
2. We could use a Docker image with the environment already in it.

Proposed Action Plan

• 1. Replace the calls to "conda" with "mamba" when the "mamba" command is available.
• 2. Run the tests

Problem Statement

Right now the yml file is a requirement for the action. We want to remove this requirement and have good defaults that are within this action's repo.

Proposed Solution

• Remove the yml file requirement by adding a default version to the action itself which is used if the file is not found in the repo. This will be the envs/build-docs.yml within this repo.
• Document what packages are contained in the default env file.

Alternatives Considered

• Continue to require the Conda env definition yml file and fail if it isn't found.
• Commit the template yml to the repo if it's not found.