From 345b5d20b6a988643e1f5e5fae86bcdb08f4948e Mon Sep 17 00:00:00 2001 From: "Michael Entrup (b. Epping)" Date: Sun, 13 Oct 2019 13:56:35 +0200 Subject: [PATCH 1/2] Creating a documentation template using Sphinx: Sphinx is configured to create the documentation for pptx-blueprint. The README.md describes how to build the documentation. --- dev_requirements.txt | 1 + docs/Makefile | 20 +++++++++++++ docs/README.md | 48 +++++++++++++++++++++++++++++ docs/conf.py | 55 ++++++++++++++++++++++++++++++++++ docs/index.rst | 49 ++++++++++++++++++++++++++++++ docs/make.bat | 35 ++++++++++++++++++++++ docs/source/modules.rst | 7 +++++ docs/source/pptx_blueprint.rst | 10 +++++++ 8 files changed, 225 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/README.md create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/source/modules.rst create mode 100644 docs/source/pptx_blueprint.rst diff --git a/dev_requirements.txt b/dev_requirements.txt index 14decf1..9ac12e8 100644 --- a/dev_requirements.txt +++ b/dev_requirements.txt @@ -1,2 +1,3 @@ -r requirements.txt pytest>=5.2.1 +Sphinx>=2.2.0 \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..ce2319d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,48 @@ +# Creating the documentation using Sphinx + +The documentation of [pptx-blueprint](https://github.com/timhoffm/pptx-blueprint) is created using [Sphinx](https://www.sphinx-doc.org/en/master/index.html#). This file describes how to update the documentation and explains the basic configuration. + + +## Updating the documentation + +On Linux make sure to have `make` installed. Go to the `docs/` directory of pptx-blueprint and run + +```bash +make html +``` + +This will create a HTML version of the documentation at `docs/_build/`. Open `docs/_build/index.html` to read the documentation. + +The directory `doces/source/` contains the automatically generated API documentation for pptx-blueprint. This one needs to be updated manually after making changes to the API. The update can be performed by running + +```bash +sphinx-apidoc -f -o source/ ../pptx_blueprint +``` + +The argument `-f` forces `sphinx-apidoc` to overwrite existing files. `-o` is used to define the output directory. + + +## Setting up Sphinx to create the documentation + +We decided to place the documentation into the sub-directory `docs/`. Inside of this directory `sphinx-quickstart` will create the basic configuration. At the wizard we decided to split up `source/` and `_build/` into separate directories. +The next step is to update `conf.py`. For `sphinx-apidoc` to work some changes are necessary: + +```python +# Extending sys.path to find the module pptx-blueprint: +import os +import sys +sys.path.insert(0, os.path.abspath('../')) + +# Activating autodoc and napoleon: +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', +] + +# Setting the theme to 'classic': +html_theme = 'classic' +``` + +[Autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) is needed to use different directives that include the documentation created with `sphinx-apidoc` into our documentation. For example `.. autoclass:: pptx_blueprint.Template` will load the automatically created documentation for the class `Template`. +[Napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) is necessary to parse docstrings that follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). +The default theme of Sphinx is [Alabaster](https://alabaster.readthedocs.io/en/latest/) is the default theme. From [the list of buildin themes](https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes) we have selected *classic* to be theme we use. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..f530bdf --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,55 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../')) + + +# -- Project information ----------------------------------------------------- + +project = 'pptx-blueprint' +copyright = '2019, Tim Hoffmann' +author = 'Tim Hoffmann' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +# 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', +] + + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'classic' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..672ec0b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,49 @@ +.. pptx-blueprint documentation master file, created by + sphinx-quickstart on Sun Oct 13 10:54:23 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +pptx-blueprint documentation +========================================== + +pptx-blueprint is a PowerPoint templating engine. The tool automatically creates presentations using some data and a ``.pptx`` file as a the layout template. + + +First steps +=========== + +.. code-block:: python + :linenos: + + import pptx_blueprint + + from pathlib import Path + + pres = pptx_blueprint.Template("template.pptx") + pres.replace_text("head_line", "My first presentation with pptx-blueprint") + pres.replace_image("title_img", Path("./img/title_img.png")) + pres.save("my_presentation.pptx") + + +The helper class ``Template`` +============================= + +This is only included to demonstrate the usage of ``.. autoclass::``. By adding the argument ``:noindex:`` this occurence of ``pptx_blueprint.Template`` is not used for the index. + +.. autoclass:: pptx_blueprint.Template + :noindex: + + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..2119f51 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..f8f52b4 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +pptx_blueprint +============== + +.. toctree:: + :maxdepth: 4 + + pptx_blueprint diff --git a/docs/source/pptx_blueprint.rst b/docs/source/pptx_blueprint.rst new file mode 100644 index 0000000..748b88d --- /dev/null +++ b/docs/source/pptx_blueprint.rst @@ -0,0 +1,10 @@ +pptx\_blueprint package +======================= + +Module contents +--------------- + +.. automodule:: pptx_blueprint + :members: + :undoc-members: + :show-inheritance: From 36a4b0b09fa457d0587fe1877eaedff9401bd425 Mon Sep 17 00:00:00 2001 From: "Michael Entrup (b. Epping)" Date: Sun, 13 Oct 2019 14:49:02 +0200 Subject: [PATCH 2/2] Adding sources used to setup Sphinx Both articles describe how to setup Sphinx. As I have used them the authors should get credit for it. --- docs/README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index ce2319d..aab441e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -45,4 +45,9 @@ html_theme = 'classic' [Autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) is needed to use different directives that include the documentation created with `sphinx-apidoc` into our documentation. For example `.. autoclass:: pptx_blueprint.Template` will load the automatically created documentation for the class `Template`. [Napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) is necessary to parse docstrings that follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). -The default theme of Sphinx is [Alabaster](https://alabaster.readthedocs.io/en/latest/) is the default theme. From [the list of buildin themes](https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes) we have selected *classic* to be theme we use. \ No newline at end of file +The default theme of Sphinx is [Alabaster](https://alabaster.readthedocs.io/en/latest/) is the default theme. From [the list of buildin themes](https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes) we have selected *classic* to be theme we use. + +## Sources + +- [An idiot’s guide to Python documentation with Sphinx and ReadTheDocs](https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/) by [Sam Nicholls](https://samnicholls.net/about/) +- [Sphinx for Python documentation](https://gisellezeno.com/tutorials/sphinx-for-python-documentation.html) by [Giselle Zeno](https://gisellezeno.com/pages/about-me.html) \ No newline at end of file