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 <steven.christe@nasa.gov>

.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.

.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

.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

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.

changelog/13.doc.1.rst

@@ -0,0 +1 @@
+Updated docs to properly use sphinx-changelog and generated a changelog

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

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()

docs/dev-guide/docs.rst

@@ -7,24 +7,22 @@ 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 <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_
 
-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
 
     `hermes_instrument.io.read_file`
 
 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 <http://www.sphinx-doc.org/en/master/ext/intersphinx.html>`_:
 
 .. code-block:: rst
@@ -70,25 +68,18 @@ For more information on how to use Sphinx, consult the `Sphinx documentation <ht
 HTML
 ^^^^
 
-To build the html documentation locally use the follownig command, in the root directory run::
+To build the html documentation locally use the following command, in the docs directory run::
 
-    $ sphinx-build docs docs/_build/html -W -b html
+    $ make html
 
 This will generate HTML documentation in the "docs/_build/html" directory.
 You can open the "index.html" file to browse the final product.
 
-PDF
-^^^
-
-To build the pdf documentation locally use the follownig command, in the root directory run::
-
-    $ sphinx-build docs docs/_build/pdf -W -b pdf
-
-This will generate HTML documentation in the "docs/_build/html" directory.
-You can open the "index.html" file to browse the final product.
+If you'd like to rebuild the documentation from scratch.
+This is normally not necessary since Sphinx will detect and only build the required changes.
+But if you are running into strange errors you may want to try this.
+The following command will wipe all generated files.
 
-Troubleshooting
----------------
-If you run into problems the following set of tips might help
+    $ make clean
 
-Delete all files that sphinx generated which are located in docs/_build/html and the docs/api folder.
+Sphinx can also build documentation as a PDF but this requires latex to be installed.

docs/dev-guide/maintainer_workflow.rst

@@ -99,7 +99,7 @@ Push to open pull request
 
 Now you need to push the changes you have made to the code to the open pull request::
 
-    $ git push git@github.com:<username>/sunpy.git HEAD:<name of branch>
+    $ git push git@github.com:<username>/hermes_instrument.git HEAD:<name of branch>
 
 You might have to add ``--force`` if you rebased instead of adding new commits.
 
@@ -122,14 +122,15 @@ 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.
 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. <https://github.com/sunpy/sunpy/blob/main/changelog/README.rst>`__.
 
@@ -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
+.. _step by step checklist: https://github.com/HERMES-SOC/hermes_core/wiki/Release-Process

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

setup.cfg

@@ -36,6 +36,7 @@ test =
 docs =
     sphinx
     sphinx-automodapi
+    sphinx-changelog
     towncrier
 
 [options.package_data]