5.2.2. Epydoc Embedded in IFrame¶
The configuration template epydoc_sphinx_iframe provides a configuration for the commands build_docx and/or build_apiref for the document type HTML. The result is an embedded Epydoc document within the directory within the Sphinx document. The integration requires an additional page with an IFrame as the container for the EPydoc document.
The provided example is based on the theme sphinx_rtd_theme for a local ReadTheDocs document style creation. The theme could be easily installed via PyPI.org.
The full-screen mode. Due to ongoing groundwork on an enhanced documentation tool the integration of Epydoc is currently kept on basic level, while the efforts are focused else. Thus some legacy options change to full-screen mode, which requires the back-button of the browser to return to the previous position. The Epydoc option Home switches back to the top of the containing document. This feature is not yet publicly available, but present on the public documents of the author.
- configuration
The integration is not fully automated. This is due to the intended support of arbitrary designs and themes. Thus the container page for the Epydoc integration has to be edited by the author of the document.
The following required steps of the creation, integration, packaging, and the continous local installation are fully automated. The commands could easily be used manually, or integrated into a CI/CD framework. This requires just the copy of the patched files into the configuration directory and the call of the command build_docx with the configuration parameter –confdir.
The current example implementation contains the files required for the ReadTheDocs theme as well as for Epydoc. The configuration is part of the package and stored within the default path:
setupddocx/configurations/epydoc/epydoc_sphinx_iframe
The contained files are listed in the following table. These are copied by the standard mechanism into the documents build directory in order to replace present files. Thus the configuration could be kept outside the patched document without changing the documents default sources.
file
remark
docsrc/index.rst
replaces index.rst of the document
docsrc/index_part_apiref_scaled.rst
adds a page with the IFrame for Epydoc
docsrc/conf.py
adds configuration variables
docsrc/epydoc.conf
standard config for epydoc, the entries
target and css must be deactivated
docsrc/epydoc.css
standard stylesheet config for epydoc
docsrc/_static/custom.css
sets some custom colors and sizes
docsrc/_static/favicon.ico
provides a demo favicon, requires ICO
docsrc/_static/logo.png
provides a demo logo, requires PNG
call
The call creates a html document within the local directory doc
python setup.py \ build_docx \ --apiref \ --conf-dir=setupdocx/configurations/epydoc/epydoc_sphinx_iframe/ \ install_docx \ --dist-dir doc # copy-and-paste for execution # for readability split acros multiple linesThe same call with detailed command line parameters:
python setup.py \ build_docx \ --doctype=html \ --docname=sphinx_epydoc \ --conf-dir=setupdocx/configurations/epydoc/epydoc_sphinx_iframe/ \ --apiref \ install_docx \ --dist-dir doc \ --docname=sphinx_epydoc # copy-and-paste for execution # for readability split acros multiple lines