lipro / publishing-withsphinx

Sphinx extension to help document publishing

publishing-withsphinx

This Sphinx extension, publishing.withsphinx, provides support for easy generation and publishing of documents with the Sphinx documentation engine.

This extension ensures versioned dependencies to other third party extensions, load and setup these extensions and provides functionality to have more fancy templates for different writer backends.

More information is available here:

• (NOT YET) Documentation: https://publishing-withsphinx.readthedocs.org/en/latest
• (NOT YET) Download: https://pypi.python.org/pypi/publishing-withsphinx
• Development: https://github.com/lipro/publishing-withsphinx

publishing-withsphinx's Issues

Remove support for 'sphinxcontrib-embedly'

The Embedly service is an commercial effort and will not be able to scale without costs. That is definitively a no-go from perspective of this project goals. I will remove the support and reduce the maintenance to me.

Backport new LaTeX configuration from Sphinx 1.5 to be backward compatible

Move the back port of app.config.latex_engine from Sphinx 1.5 into the publishing-withsphinx implementation to be compatible to all Sphinx versions down to 1.2 without the need to expand any single conf.py file.

Currently this back port was multiply implemented in different conf.py files:

• tests/roots/conf.py::187
• tests/roots/test-contrib-tikz/conf.py::31

Add support for Sphinx 1.7

It's time to support more current releases of Sphinx. That issue That issue will handle all changes related to Sphinx 1.7.

Enhance section "Compatibility Matrix" in package documentation

The chapter Compatibility Matrix is insufficient. The mapping from Sphinx extensions to Sphinx versions is missing. A automatically representation should be preferred.

Travis-CI fails on blockdiag test for LaTeX

For unknown reasons the integration test for blockdiag fails for the LaTeX writer.

Fix Travis-CI matrix

Because of unknown reason the execution of nosetests fails for each tox environment wich has following constellation: Sphinx 1.2 and any Python 3 (py{33,34,35}-sphinx1.2). In a local Python 3 virtual environment all is fine.

Mal formatted LaTeX sequence in 'traceable-matrix'

Currently it's not possible to generate a proper tractability matrix for LaTeX/PDF documents. All roles .. traceable-matrix:: must be disabled for LaTeX build (negated as .. only:: html). The error source seems to be in the related Sphinx extension sphinxcontrib-traceables.

Avoid the deployment of copied DejaVuSans font

I've split the old issue #1 that was solved to process the blockdiag tests on Travis. For details about the font problematic see issue #1, here is the quote:

The core of this bug has side effects with the TikZ integration (as far as I can survey). TikZ depends on a proper XeLaTeX installation newer then 2009, but the version that comes with Ubuntu 12.04, the current default system on Travis-CI, is too old. That's why the Travis-CI configuration will install the complete Xe/LaTeX environment from Launchpad's TeX Live Backports PPA.

I believe as an result of this newer LaTeX environment, the underlying blockdiag Python module will not found any default font to render SVG or PDF. That must be investigated in details in the future. For a temporary solution for the test suit, the DejaVuSans will copied into the test suite fixtures and deploy with the source package.

List of supported Sphinx extensions in the package documentation

There is no list of supported Sphinx extensions. A automatically representation should be prefered. A appropriate functionality should being found.

Improve the unit tests

The current implementation in a single file is too simple and inflexible for further tasks. Have a look to the Sphinx project and take the best from there.

Add support for Sphinx 1.6

It's time to support more current releases of Sphinx. That issue That issue will handle all changes related to Sphinx 1.6.

Remove support for Python 2 switch to Python 3

It's year 2019 and time to remove support of the deprecated technology Python 2. With current knowledge, the maintenance of Python 2 will be discontinued in January 2020:

• python/devguide#344
• https://www.python.org/dev/peps/pep-0373/

Remove support for Sphinx 1.2

To reduce the maintenance costs the support for Sphinx 1.2 have to remove. There are many many special dependencies that have to respect, that increase the complexity of project's run-time configuration and test environment and that all for an more than four years old release.

Reduce the build time overhead on Travis CI

The build time on Travis CI is too much, because of the full LaTeX installation in every matrix run. We do not need this for all tests, only for documentation.

Add support for Sphinx 1.8

It's time to support more current releases of Sphinx. That issue That issue will handle all changes related to Sphinx 1.5.

Add support for Sphinx 1.5

It's time to support more current releases of Sphinx. That issue That issue will handle all changes related to Sphinx 1.5.

Travis-CI will fail on documentation build with the new Sphinx 1.8 support

See: https://travis-ci.org/rexut/publishing-withsphinx/jobs/488576168

Error is:

Can't exec "xindy": No such file or directory at (eval 9) line 14.

With Sphinx 1.8 the LaTeX Makefile was completely rewritten and depends on the sorted and tagged index generator xindy. The binary can found in the Ubuntu package xindy that will not installed by default with package texlive-full. So we have to install it manually by an additional entry in the Travis YAML file.

The documentation has to split into different parts

In order to make information accessible to different interested persons quickly, the documentation should be divided into different sections:

• User’s Manual
• Programmer’s Manual
• Regulatory Affairs
• Sphinx Cheat Sheet
• Appendix