From 566fe8d1e5c05ead0ff81d862f223e4c3241c06c Mon Sep 17 00:00:00 2001 From: tonyastrofig <84603637+tonyastrofig@users.noreply.github.com> Date: Mon, 18 Apr 2022 11:34:54 -0400 Subject: [PATCH] Add make to to build Sphinx docs and configuration fix for changelogs generation (#13) * Adding docstring to __init__.py Adding the apt-get update and install make to the Dockerfule * added a make clean command * updated docs to use make command * removed mention of sunpy in maintainer docs * Update Dockerfile * added changelog file * fixed to enable changelog to work in docs * fixed changelog files * update github action to use make * Update docs.yml * added changelog to requirements Co-authored-by: Steven Christe --- .devcontainer/Dockerfile | 1 + .devcontainer/requirements.txt | 1 + .github/workflows/docs.yml | 3 ++- changelog/12.doc.1.rst | 1 + changelog/13.doc.1.rst | 1 + docs/Makefile | 4 ++++ docs/conf.py | 16 +------------ docs/dev-guide/docs.rst | 31 +++++++++----------------- docs/dev-guide/maintainer_workflow.rst | 7 +++--- docs/whatsnew/changelog.rst | 6 +++-- setup.cfg | 1 + 11 files changed, 31 insertions(+), 41 deletions(-) create mode 100644 changelog/12.doc.1.rst create mode 100644 changelog/13.doc.1.rst diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 1abca4e..61672ff 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -7,6 +7,7 @@ FROM mcr.microsoft.com/vscode/devcontainers/base:ubuntu-20.04 # RUN bash -i -c 'pip3 install --user --no-use-pep517 -e .[all]' RUN apt-get update && \ apt-get -y upgrade && \ + apt-get install make && \ apt-get install --no-install-recommends -y python3.8 python3-pip python3.8-dev pylint # [Optional] Uncomment this line to install global node packages. diff --git a/.devcontainer/requirements.txt b/.devcontainer/requirements.txt index 0ff61a4..2018b33 100644 --- a/.devcontainer/requirements.txt +++ b/.devcontainer/requirements.txt @@ -11,5 +11,6 @@ pytest-cov pre-commit sphinx # for documentation sphinx-automodapi # for documentation +sphinx-changelog # for changelog in documentation towncrier # for building changelog for documentation ipython # for easier debugging diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 1cd86bf..85d8e9e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -29,4 +29,5 @@ jobs: python -m pip install --upgrade pip python -m pip install -e .[docs] - name: Build docs - run: sphinx-build docs docs/_build/html -W -b html + working-directory: ./docs + run: make html diff --git a/changelog/12.doc.1.rst b/changelog/12.doc.1.rst new file mode 100644 index 0000000..55effc4 --- /dev/null +++ b/changelog/12.doc.1.rst @@ -0,0 +1 @@ +Added `make` to the container to enable building docs with it. Updated dev docs to describe how to use it and how to clean. \ No newline at end of file diff --git a/changelog/13.doc.1.rst b/changelog/13.doc.1.rst new file mode 100644 index 0000000..67f5d4f --- /dev/null +++ b/changelog/13.doc.1.rst @@ -0,0 +1 @@ +Updated docs to properly use sphinx-changelog and generated a changelog \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..3a626f8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -14,6 +14,10 @@ help: .PHONY: help Makefile +clean: + rm -rf $(BUILDDIR) + rm -rf api + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/docs/conf.py b/docs/conf.py index 92ca67e..c8f0249 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,6 +39,7 @@ "sphinx.ext.mathjax", "sphinx_automodapi.automodapi", "sphinx_automodapi.smart_resolver", + "sphinx_changelog", ] # Set automodapi to generate files inside the generated directory @@ -120,18 +121,3 @@ "-Gfontsize=10", "-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif", ] - - -""" -Write the latest changelog into the documentation. -""" -target_file = os.path.abspath("./whatsnew/latest_changelog.txt") -try: - from sunpy.util.towncrier import generate_changelog_for_docs - - if is_development: - generate_changelog_for_docs("../", target_file) -except Exception as e: - print(f"Failed to add changelog to docs with error {e}.") -# Make sure the file exists or else sphinx will complain. -open(target_file, "a").close() diff --git a/docs/dev-guide/docs.rst b/docs/dev-guide/docs.rst index b95f1a8..b2cd109 100644 --- a/docs/dev-guide/docs.rst +++ b/docs/dev-guide/docs.rst @@ -7,16 +7,14 @@ Documentation Rules Overview ======== -All code must be documented and we follow these style conventions described here: +All code must be documented and we follow the style conventions described here: * `numpydoc `_ -We recommend familiarizing yourself with this style. - Referring to other code ----------------------- -To link to other methods, classes, or modules in your repo you have to use backticks, for example: +To link to methods, classes, or modules in your repo you have to use backticks, for example: .. code-block:: rst @@ -24,7 +22,7 @@ To link to other methods, classes, or modules in your repo you have to use backt generates a link like this: `hermes_instrument.io.read_file`. -Other packages can also be linked via +Links can also be generated to external packages via `intersphinx `_: .. code-block:: rst @@ -70,25 +68,18 @@ For more information on how to use Sphinx, consult the `Sphinx documentation /sunpy.git HEAD: + $ git push git@github.com:/hermes_instrument.git HEAD: You might have to add ``--force`` if you rebased instead of adding new commits. @@ -122,7 +122,7 @@ Current labelling guidelines: Updating and Maintaining the Changelog ====================================== -The changelog will be read by users, so this description should be aimed at sunpy users instead of describing internal changes which are only relevant to the developers. +The changelog will be read by users, so this description should be aimed at users instead of describing internal changes which are only relevant to the developers. The current changelog is kept in the file "CHANGELOG.rst" at the root of the repository. You do not need to update this file as we use `towncrier`_ to update our changelog. @@ -130,6 +130,7 @@ This is built and embedded into our documentation. Towncrier will automatically reflow your text, so it will work best if you stick to a single paragraph, but multiple sentences and links are OK and encouraged. You can install towncrier and then run ``towncrier --draft`` if you want to get a preview of how your change will look in the final release notes. +This tool was built by the SunPy community and they provide a great guide on how to use it. `Instructions on how to write a changelog. `__. @@ -140,4 +141,4 @@ Releases We have a `step by step checklist`_ on the Wiki on how to make a release. -.. _step by step checklist: https://github.com/sunpy/sunpy/wiki/Home%3A-Release-Checklist \ No newline at end of file +.. _step by step checklist: https://github.com/HERMES-SOC/hermes_core/wiki/Release-Process \ No newline at end of file diff --git a/docs/whatsnew/changelog.rst b/docs/whatsnew/changelog.rst index 37943cf..a3678c4 100644 --- a/docs/whatsnew/changelog.rst +++ b/docs/whatsnew/changelog.rst @@ -4,5 +4,7 @@ Full Changelog ************** -.. include:: latest_changelog.txt -.. include:: ../../CHANGELOG.rst +.. changelog:: + :towncrier: ../../ + :towncrier-skip-if-empty: + :changelog_file: ../../CHANGELOG.rst diff --git a/setup.cfg b/setup.cfg index 9dbb7da..becffdf 100644 --- a/setup.cfg +++ b/setup.cfg @@ -36,6 +36,7 @@ test = docs = sphinx sphinx-automodapi + sphinx-changelog towncrier [options.package_data]