smile-sa/sphinx-versions

Sphinx extension that allows building versioned docs for self-hosting

sphinx-versions

Sphinx extension that allows building versioned docs for self-hosting.

• Python 3.4, and 3.5 supported on Linux and OS X.
• Python 3.4, and 3.5 supported on Windows (both 32 and 64 bit versions of Python).

Full documentation: https://sphinx-versions.readthedocs.io

This project is, for the most part, a fork of https://github.com/Robpol86/sphinxcontrib-versioning, with some additions and removals.

How to use

Most basic usage:

sphinx-versions --help
sphinx-versions build --help

Changelog

This project adheres to Semantic Versioning.

1.1.3 - 2019-07-18

Changes

• Fix pdf copy target directory

1.1.2 - 2019-07-18

Changes

• Removes the rest of unicode function calls

1.1.1 - 2019-07-18

Changes

• Removes compatibility with Python 2 (and make it work properly on Pyhton 3 : removing a call to unicode function)

1.1.0 - 2019-07-18

Changes

• Add -P pdf-file-name.pdf option, thanks to Anybotics fork <https://github.com/ANYbotics/sphinx-versions>

1.0.1 - 2019-04-23

Changes

• Update sphinx version from 1.8.4 to 1.8.5

1.0.0 - 2018-12-08

Changes

• From sphinxcontrib-versionning v2.2.1, added compatibility with Sphinx 1.8.2.
• From sphinxcontrib-versionning v2.2.1, removed push commands, considered not core for our own usage.
• Migrates to pipenv as the recommanded installation process.
• Use -s option instead of --no-patch in git show (this is for git 1.8.3.1 compatibility).

sphinx-versions's Issues

sphinx-versions: command not found

I am trying to install sphinx-versions extension from the sphinx-versions official documentation.

I have installed pip3, pip, and pipenv.

$ pip3 --version
pip 20.0.2 from /usr/lib/python3/dist-packages/pip (python 3.8)

$ pipenv --version
pipenv, version 11.9.0

I install sphinx-versions using the below command:

$ pipenv install --skip-lock sphinx-versions

Creating a virtualenv for this project…
Using /usr/bin/python3 (3.8.10) to create virtualenv…
⠋ModuleNotFoundError: No module named 'virtualenv.seed.via_app_data'
Error while trying to remove the /home/sachin/.local/share/virtualenvs/docs-39RfKTWI env: 
No such file or directory

Virtualenv location: 
Installing sphinx-versions…
Looking in indexes: https://pypi.python.org/simple
Requirement already satisfied: sphinx-versions in /home/sachin/.local/lib/python3.8/site-packages (1.1.3)
Requirement already satisfied: sphinx in /home/sachin/.local/lib/python3.8/site-packages (from sphinx-versions) (5.1.0)
...
...
...
Adding sphinx-versions to Pipfile's [packages]…

Now, when I sphinx-versions --help, it says command not found.

Have I installed the extension properly?

Use of "add_stylesheet()" causes Sphinx >=4.0 to fail

Sphinx 4.0 has removed the Sphinx.add_stylesheet() method that was deprecated since Sphinx 1.8.
See also sphinx-doc/sphinx#7747.

Python 3.10 requires Sphinx >=4.2, so this problem also prevents using sphinx-versions on Python 3.10.

Here is how it fails (e.g. from this log):

Running Sphinx v4.2.0

Exception occurred:
  File "/opt/hostedtoolcache/Python/3.10.0/x64/lib/python3.10/site-packages/sphinxcontrib/versioning/sphinx_.py", line 156, in setup
    app.add_stylesheet('banner.css')
AttributeError: 'Sphinx' object has no attribute 'add_stylesheet'
The full traceback has been saved in /tmp/sphinx-err-cy6e51wu.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Process Process-2:
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.10.0/x64/lib/python3.10/multiprocessing/process.py", line 315, in _bootstrap
    self.run()
  File "/opt/hostedtoolcache/Python/3.10.0/x64/lib/python3.10/multiprocessing/process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "/opt/hostedtoolcache/Python/3.10.0/x64/lib/python3.10/site-packages/sphinxcontrib/versioning/sphinx_.py", line 210, in _build
    raise SphinxError
sphinx.errors.SphinxError

Please change to using the recommended replacement function in sphinx-versions.

I verified this with sphinx-versions 1.0.0 and 1.1.3, and with Sphinx 4.2.0 and 4.3.1 (on Python 3.10 on macOS).

Click 8.1.0 removed deprecated function get_os_args used by sphinx-versions

From https://github.com/zhmcclient/zhmc-ansible-modules/runs/5803700243?check_suite_focus=true#step:11:1:

sphinx-versioning -l docs/source/conf.py build docs/source docs_build
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.9.10/x64/bin/sphinx-versioning", line 33, in <module>
    sys.exit(load_entry_point('sphinx-versions===1.1.3.post-am1', 'console_scripts', 'sphinx-versioning')())
  File "/opt/hostedtoolcache/Python/3.9.10/x64/lib/python3.9/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.9.10/x64/lib/python3.9/site-packages/sphinxcontrib/versioning/__main__.py", line 72, in main
    argv = kwargs.pop('args', click.get_os_args())
AttributeError: module 'click' has no attribute 'get_os_args'

Environment:

• Python 3.9.10
• Click 8.1.2
• sphinx-versions from my fork

Click 8.1.0 removed the deprecated function get_os_args(): pallets/click#2130

sphinx-versions needs to be updated to change the use of get_os_args() to use sys.args.

rtd theme crashes

Using the sphinx-rtd-theme crashes in pathtopdf

Traceback (most recent call last):
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\builders\html.py", line 1027, in handle_page
    output = self.templates.render(templatename, ctx)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\jinja2glue.py", line 207, in render
    return self.environment.get_template(template).render(context)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\jinja2\asyncsupport.py", line 76, in render
    return original_render(self, *args, **kwargs)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\jinja2\environment.py", line 1008, in render
    return self.environment.handle_exception(exc_info, True)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\jinja2\environment.py", line 780, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\jinja2\_compat.py", line 37, in reraise
    raise value.with_traceback(tb)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\themes\basic\page.html", line 10, in <module>
    {%- extends "layout.html" %}
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\jinja2\environment.py", line 1005, in render
    return concat(self.root_render_func(self.new_context(vars)))
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\themes\basic\page.html", line 14, in root
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx_rtd_theme\layout.html", line 179, in root
    <div class="wy-nav-content">
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinxcontrib\versioning\_templates\versions.html", line 19, in root
    <dt>Branches</dt>
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\jinja2\sandbox.py", line 387, in getattr
    value = getattr(obj, attribute)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinxcontrib\versioning\versions.py", line 205, in tags
    return [(r['name'], self.vpathto(r['name']), self.pathtopdf(r['name'])) for r in self.remotes if r['kind'] == 'tags']
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinxcontrib\versioning\versions.py", line 205, in <listcomp>
    return [(r['name'], self.vpathto(r['name']), self.pathtopdf(r['name'])) for r in self.remotes if r['kind'] == 'tags']
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinxcontrib\versioning\versions.py", line 256, in pathtopdf
    components += [os.path.splitext(self.pdf_file)[0]]
  File "C:\Users\yedema21\AppData\Local\Programs\Python\Python38\lib\ntpath.py", line 196, in splitext
    p = os.fspath(p)
TypeError: expected str, bytes or os.PathLike object, not NoneType

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\cmd\build.py", line 276, in build_main
    app.build(args.force_all, filenames)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\application.py", line 353, in build
    self.builder.build_update()
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\builders\__init__.py", line 297, in build_update
    self.build(to_build,
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\builders\__init__.py", line 361, in build
    self.write(docnames, list(updated_docnames), method)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\builders\__init__.py", line 535, in write
    self._write_serial(sorted(docnames))
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\builders\__init__.py", line 545, in _write_serial
    self.write_doc(docname, doctree)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\builders\html.py", line 622, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinx\builders\html.py", line 1034, in handle_page
    raise ThemeError(__("An error happened in rendering the page %s.\nReason: %r") %
sphinx.errors.ThemeError: An error happened in rendering the page api/flow.
Reason: TypeError('expected str, bytes or os.PathLike object, not NoneType')

Theme error:
An error happened in rendering the page api/flow.
Reason: TypeError('expected str, bytes or os.PathLike object, not NoneType')
Process Process-2:
Traceback (most recent call last):
  File "C:\Users\yedema21\AppData\Local\Programs\Python\Python38\lib\multiprocessing\process.py", line 313, in _bootstrap
    self.run()
  File "C:\Users\yedema21\AppData\Local\Programs\Python\Python38\lib\multiprocessing\process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "c:\users\yedema21\git\flow\venv\lib\site-packages\sphinxcontrib\versioning\sphinx_.py", line 213, in _build
    raise SphinxError
sphinx.errors.SphinxError
=> sphinx-build failed for branch/tag: master

stuck building documentation

Hi,

environment created with versions below:

Sphinx==2.2.1
sphinx-prompt==1.1.0
sphinx-rtd-theme==0.4.3
sphinx-versions==1.1.3

the building gets always stuck like this:

=> Reading config from source/conf.py...
Running Sphinx v2.2.1
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 67 source files that are out of date
updating environment: [new config] 67 added, 0 changed, 0 removed
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done 
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices...  genindexdone 
writing additional pages...  searchdone
copying images... [100%] Content/images/Installation/cmix_flavour_11.png
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in ../../../../../../../var/folders/t_/kztj0hf94n30rxhf82blqv_c0000gn/T/tmphcz7mja3sphinxcontrib_versioning.

This happens with several sphinx-doc projects.

Note: The pending pull request is applied.

no more info if run with debug mode.

Any help or comment is very much appreciated.

Is this package still maintained?

@cgachot @hogabrie Hi, is this Python package still maintained by you? Can I help in any way?