More

.github/workflows/docs.yaml

@@ -62,16 +62,16 @@ jobs:
   #       name: Configure AWS Credentials
   #       uses: aws-actions/configure-aws-credentials@v1
   #       with:
-  #         aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-  #         aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-  #         aws-region: ${{ secrets.AWS_REGION }}
+  #         aws-access-key-id: ${{ secrets.DOCS_AWS_ACCESS_KEY_ID }}
+  #         aws-secret-access-key: ${{ secrets.DOCS_AWS_SECRET_ACCESS_KEY }}
+  #         aws-region: ${{ secrets.DOCS_AWS_REGION }}
 
   #     - id: upload-to-s3
   #       name: Upload documentation to Amazon S3
   #       uses: datadesk/delivery-deploy-action@v1
   #       with:
-  #         bucket: ${{ secrets.AWS_BUCKET }}
-  #         base-path: ${{ secrets.AWS_BASE_PATH }}
+  #         bucket: ${{ secrets.DOCS_AWS_BUCKET }}
+  #         base-path: ${{ secrets.DOCS_AWS_BASE_PATH }}
   #         dir: ./docs/
   #         should-cache: false
   #         use-accelerate-endpoint: false

CONTRIBUTING.md

@@ -20,6 +20,26 @@ Run tests.
 pipenv run pytest
 ```
 
+## Documentation
+
+The repository includes a ready-to-serve documentation site managed by Python's [Sphinx](https://www.sphinx-doc.org/en/master/) framework.
+
+The configuration is stored in the `docs` directory. The default settings in `docs/conf.py` include several common Sphinx extensions. The documentation is written in [Markdown](https://en.wikipedia.org/wiki/Markdown) files stored within the directory. If you plan to publish documentation, you should started by editing `docs/index.md` and go from there. You can learn more about the options to available in the [MyST](https://myst-parser.readthedocs.io/en/latest/intro.html) guide to writing Markdown in Sphinx.
+
+To build the documentation as a bundle of HTML files, run the following command:
+
+```zsh
+cd docs && pipenv run make html``
+```
+
+You can launch a preview site with the following command:
+
+```zsh
+cd docs && pipenv run make livehtml
+```
+
+The documentation site is build by default in a [GitHub Actions workflow](https://github.com/palewire/python-open-source-template/blob/main/.github/workflows/docs.yaml) that runs on every push to the repository. If you provide the proper credentials, it will also automatically publish the documentation to an Amazon S3 bucket.
+
 ## Releasing
 
 # Releasing