Git Product home page Git Product logo

sphinxcontrib-versioning's Introduction

sphinxcontrib-versioning

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

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

📖 Full documentation: https://sphinxcontrib-versioning.readthedocs.io

Documentation Status Build Status Windows Build Status Coverage Status Latest Version

Quickstart

Install:

pip install sphinxcontrib-versioning

Usage:

sphinx-versioning --help
sphinx-versioning build --help
sphinx-versioning push --help

Changelog

This project adheres to Semantic Versioning.

2.2.1 - 2016-12-10

Added
  • Time value of html_last_updated_fmt will be the last git commit (authored) date.
Fixed
  • Unhandled KeyError exception when banner main ref fails pre-build.
  • #26
  • #27

2.2.0 - 2016-09-15

Added
  • Windows support.
Fixed

2.1.4 - 2016-09-03

Fixed
  • banner.css being overridden by conf.py: #23

2.1.3 - 2016-08-24

Fixed
  • Stopped blocking users from overriding their layout.html. Using another approach to inserting the banner.

2.1.2 - 2016-08-24

Fixed
  • Cloning from push remote instead of origin. If HTML files are pushed to another repo other than origin it doesn't make sense to clone from origin (previous files won't be available).

2.1.1 - 2016-08-23

Added
  • Command line option: --push-remote
Fixed
  • Copy all remotes from the original repo to the temporarily cloned repo when pushing built docs to a remote. Carries over all remote URLs in case user defines a different URL for push vs fetch.

2.1.0 - 2016-08-22

Added
  • Option to enable warning banner in old/development versions. Similar to Jinja2's documentation.
  • Command line options: --banner-greatest-tag --banner-recent-tag --show-banner --banner-main-ref
  • Jinja2 context functions: vhasdoc() vpathto()
  • Jinja2 context variables: scv_show_banner scv_banner_greatest_tag scv_banner_main_ref_is_branch scv_banner_main_ref_is_tag scv_banner_main_version scv_banner_recent_tag
Changed
  • Root ref will also be built in its own directory like other versions. All URLs to root ref will point to the one in that directory instead of the root. More info: #15
  • Renamed Jinja2 context variable scv_is_root_ref to scv_is_root.
Fixed
Removed
  • Jinja2 context variables: scv_root_ref_is_branch scv_root_ref_is_tag

2.0.0 - 2016-08-15

Added
  • --git-root command line option.
  • --whitelist-branches and --whitelist-tags command line options.
  • --local-conf and --no-local-conf command line options.
  • Load settings from conf.py file and command line arguments instead of just the latter.
Changed
  • Renamed command line option --prioritize to --priority.
  • Renamed command line option -S to -s.
  • --chdir, --no-colors, and --verbose must be specified before build/push and the other after.
  • --sort no longer takes a comma separated string. Now specify multiple times (like --grm-exclude).
  • Renamed --sort value "chrono" to "time".
  • Reordered positional command line arguments. Moved REL_SOURCE before the destination arguments.
  • Renamed command line option -C to -N for consistency with sphinx-build.
Fixed
  • Exposing sphinx-build verbosity to SCVersioning. Specify one -v to make SCVersioning verbose and two or more to make sphinx-build verbose.
  • Using --no-colors also turns off colors from sphinx-build.
  • #16

1.1.0 - 2016-08-07

Added
  • Exposing Jinja2 context variables: scv_is_branch scv_is_root_ref scv_is_tag scv_root_ref_is_branch scv_root_ref_is_tag scv_is_greatest_tag scv_is_recent_branch scv_is_recent_ref scv_is_recent_tag
Changed
  • Version links point to that version of the current page if it exists there.
Fixed

1.0.1 - 2016-08-02

Fixed
  • easy_install: #4

1.0.0 - 2016-07-23

  • Initial release.

sphinxcontrib-versioning's People

Contributors

brechtm avatar carlodri avatar derpferd avatar geier avatar robpol86 avatar timkam avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

sphinxcontrib-versioning's Issues

Documentation improvements

Thank you very much for that great plugin! I think this adds a lot of value but unfortunately it's very complex to get it up and running as most options are not documented at all. Could you please add/extend the documentation to include:

  • documentation of command line arguments
  • minimal example how to configure conf.py.
  • description how tags/branches can be used

Thank a lot.

Separate handling of release candidates

As I understand it, we basically have two options for the "default" root version of the docs: master (or some other branch of choice) or the latest (or highest by semver ordering) tag.

This logic doesn't quite work when the latest tag is a pre-release and master is development. For example, I have a project where master is the development version, tag 0.4.3 is the latest stable release, and 0.5.0rc0 is the most recent tag. (I think this is not an uncommon scenario.) In this case, it would be nice to have an option to build docs for release candidates/pre-releases, but keep the default as the highest non-rc tag.

Does this seem reasonable, and would it be difficult to pull off?

(Unrelated: thanks for building this package. It's awesome!)

Using the same environment for every build seems to break autodoc?

I was looking at migrating from RTD to sphinxcontrib-versioning, but my project makes extensive use of autodoc, and I was running into problems due to this. RTD always sets up a fresh virtualenv, installs the project into it, and then uses that virtualenv to do the build, so the version of the project that autodoc sees always matches the version of the docs being built.

It looks like sphinxcontrib-versioning doesn't have any way to do this currently – it always builds all the docs in the same environment. Is that correct? Would it be possible to do a fresh-virtualenv-per-build approach instead?

Fix KeyError when banner tag fails to build.

# Sphinx version: 1.4.8
# Python version: 3.5.1 (CPython)
# Docutils version: 0.13.1 release
# Jinja2 version: 2.8
# Last messages:
#   
#   looking for now-outdated files...
#   none found
#   pickling environment...
#   done
#   checking consistency...
#   done
#   preparing documents...
#   done
#   writing output... [ 10%] banner
# Loaded extensions:
#   sphinxcontrib.googleanalytics (0.1) from /Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinxcontrib/googleanalytics.py
#   alabaster (0.7.9) from /Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/alabaster/__init__.py
#   sphinxcontrib.versioning.sphinx_ (2.2.0) from /Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinxcontrib/versioning/sphinx_.py
Traceback (most recent call last):
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/cmdline.py", line 244, in main
    app.build(opts.force_all, filenames)
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/application.py", line 297, in build
    self.builder.build_update()
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 251, in build_update
    'out of date' % len(to_build))
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 322, in build
    self.write(docnames, list(updated_docnames), method)
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 360, in write
    self._write_serial(sorted(docnames), warnings)
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 368, in _write_serial
    self.write_doc(docname, doctree)
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/builders/html.py", line 454, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/builders/html.py", line 810, in handle_page
    templatename, ctx, event_arg)
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/application.py", line 555, in emit_firstresult
    for result in self.emit(event, *args):
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinx/application.py", line 551, in emit
    results.append(callback(self, *args))
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinxcontrib/versioning/sphinx_.py", line 92, in html_page_context
    banner_main_remote = versions[cls.BANNER_MAIN_VERSION] if cls.SHOW_BANNER else None
  File "/Users/robpol86/workspace/sphinxcontrib-versioning/.tox/docsV/lib/python3.5/site-packages/sphinxcontrib/versioning/versions.py", line 187, in __getitem__
    raise KeyError(item)
KeyError: 'v2.2.0'

Support themes inherited from sphinx_rtd_theme

versions.html checks to make sure html_theme == sphinx_rtd_theme. We created a theme based off of sphinx_rtd_theme, and had to copy a modified versions.html into our theme && remove the conditional in there in order to get the versions dropdown to show. On an upgrade of sphinxcontrib-versioning, if versions.html is refactored, we won't get the latest and greatest changes.

Would like a way to either:
A) Provide a str/tuple of strs referencing additional sphinx_rtd_theme-like themes.
B) Introspect the specified theme to figure out if it inherits from sphinx_rtd_theme.

Usage with breathe?

Hello,

I use sphinx in combination with https://github.com/michaeljones/breathe. So the build works now but my problem is that breath use the xml output from doxygen also in the sphinx html output. When I run your extension i also updated my sphinx build in a way that doxygen is builded before. But the problem is that the xml folder is not gathered by the sphinxcontrib-versioning. Can I set a path which should also be copied or so? So it is like a static folder but is also generated on the fly.

Document last updated.

Document new feature where last git authored date is set as last updated for html_last_updated_fmt.

Keep duplicate of root-ref in its own directory (future proof).

  1. Sometimes people edit URLs to go to the latest version (e.g. they're on v1.0.1 and they know v2.0.0 is the latest so they go there directly). If v2.0.0 is the latest they'll get a 404 since it's the root ref. Once v2.0.1 is out then /v2.0.0/index.html works.
  2. When the developer switches root ref to master until the next release, /v2.0.0/index.html will exist. Then they switch back the root ref to greatest tag and now /v2.0.0/index.html doesn't work until they make the release.

Solution: when building, build the root ref twice. Once in the root and again in /.

rtd theme navigation collides with rst-versions

I am working with Sphinx 1.7.6, rtd theme 0.2.4, and sphinx-versioning 2.2.1.

I have noticed that the div at the bottom of the navigation column to contain the version info and version selection (rst-versions) sits on top of the navigation table of contents (toc) column - but it also hides the last one or two entries at the bottom of the toc (if the docs and the toc is long enough and currently expanded to require scrolling of the toc). A user of the docs cannot scroll the last entries into view.

Example:
image

Could someone suggest where I might need to adjust the CSS for the theme in order to make sure that nothing is hidden in the toc?

'StandaloneHTMLBuilder' has no attribute 'default_sidebars'

Getting this error with sphinx 1.6.3 - a quick look at this class does indeed show that it doesn't have this attribute any more - but previous versions did.

# Sphinx version: 1.6.3
# Python version: 3.5.2 (CPython)
# Docutils version: 0.13.1 release
# Jinja2 version: 2.9.6
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "/tmp/venv/lib/python3.5/site-packages/sphinx/cmdline.py", line 305, in main
    opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
  File "/tmp/venv/lib/python3.5/site-packages/sphinx/application.py", line 234, in __init__
    self._init_builder()
  File "/tmp/venv/lib/python3.5/site-packages/sphinx/application.py", line 312, in _init_builder
    self.emit('builder-inited')
  File "/tmp/venv/lib/python3.5/site-packages/sphinx/application.py", line 489, in emit
    return self.events.emit(event, self, *args)
  File "/tmp/venv/lib/python3.5/site-packages/sphinx/events.py", line 79, in emit
    results.append(callback(*args))
  File "/tmp/venv/lib/python3.5/site-packages/sphinxcontrib/versioning/sphinx_.py", line 60, in builder_inited
    app.config.html_sidebars['**'] = StandaloneHTMLBuilder.default_sidebars + ['versions.html']
AttributeError: type object 'StandaloneHTMLBuilder' has no attribute 'default_sidebars'

Add AppVeyor support.

Not supporting Windows from the beginning was a mistake. Add in Windows support for AppVeyor.

Build fails for release and forks, advice?

Hi!

I understand that the status of sphinxcontrib-versioning is a bit complicated, but I gather from reading from the issues and PRs and from looking at a few doc setups that people have this working. I was wondering if someone could help me with an issue I haven't found reported here on the repo.

Running sphinx-versioning build with the pypi version I get the error documented in issue #66 fixed in PR #69. However, running @z00sts' PR branch quits with a file not found error.

I've also tried @leokoppel's fork, but there it hangs after two runs of doc building and no files found in the reported path (/tmp/tmp*sphinxcontrib_versioning).

Anyone encountered something similar or could give some points towards getting this to work with compas-dev/compas?

General info

$ python --version
Python 3.6.9

$ pip freeze | grep -i sphinx
nbsphinx==0.4.3
Sphinx==2.2.0
sphinx-compas-theme==0.4.1
sphinxcontrib-applehelp==1.0.1
sphinxcontrib-devhelp==1.0.1
sphinxcontrib-htmlhelp==1.0.2
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.2
sphinxcontrib-serializinghtml==1.1.3
sphinxcontrib-versioning==2.2.1

$ git remote -v

origin          [email protected]:compas-dev/compas.git (fetch)
origin          [email protected]:compas-dev/compas.git (push)

Logs

$ pip install git+https://github.com/z00sts/[email protected]
$ sphinx-versioning -L build -i -r master docs /dist/docs
=> Gathering info about the remote git repository...
=> Getting list of all remote branches/tags...
=> Found: docs-pull-req footnote-fix master patch-1 pathlib_support quick-fix-clr-pythonnet sphinx-versioning update_robot worbit-patch-1 0.1.0 0.1.0-drx_numpy_callback 0.1.0-facenetwork_import 0.1.0-subd_ck_example_imports 0.1.0-viewer_glut_title_str 0.1.1 0.1.1-import_error_smoothing_cpp 0.1.1-import_problems_cpp_versions 0.1.1-leaves_after_embedding 0.1.1-rhino_utility_aliases 0.1.1-xfunc_callback_args 0.1.1_ga_bugfix v0.3.0 v0.3.1 v0.3.2 v0.3.3 v0.3.4 v0.3.5 v0.3.6 v0.4.0 v0.4.1 v0.4.10 v0.4.11 v0.4.12 v0.4.13 v0.4.14 v0.4.15 v0.4.16 v0.4.17 v0.4.18 v0.4.19 v0.4.2 v0.4.20 v0.4.21 v0.4.22 v0.4.23 v0.4.3 v0.4.4 v0.4.5 v0.4.6 v0.4.7 v0.4.8 v0.4.9 v0.5.0 v0.5.1 v0.5.2 v0.6.0 v0.6.1 v0.6.2 v0.7.0 v0.7.1 v0.7.2
=> With docs: docs-pull-req footnote-fix master patch-1 pathlib_support quick-fix-clr-pythonnet sphinx-versioning update_robot worbit-patch-1 v0.3.0 v0.3.1 v0.3.2 v0.3.3 v0.3.4 v0.3.5 v0.3.6 v0.4.0 v0.4.1 v0.4.10 v0.4.11 v0.4.12 v0.4.13 v0.4.14 v0.4.15 v0.4.16 v0.4.17 v0.4.18 v0.4.19 v0.4.2 v0.4.20 v0.4.21 v0.4.22 v0.4.23 v0.4.3 v0.4.4 v0.4.5 v0.4.6 v0.4.7 v0.4.8 v0.4.9 v0.5.0 v0.5.1 v0.5.2 v0.6.0 v0.6.1 v0.6.2 v0.7.0 v0.7.1 v0.7.2
=> Root ref is: master
=> Pre-running Sphinx to collect versions' master_doc and other info.
usage: sphinx-versioning [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
sphinx-versioning: error: cannot find files ['/tmp/tmpm9pm2hi8sphinxcontrib_versioning']
=> sphinx-build failed for branch/tag: master
Failure.
$ pip install git+https://github.com/leokoppel/sphinxcontrib-versioning
$ sphinx-versioning -L build -i -r master docs /dist/docs
=> Gathering info about the remote git repository...
=> Getting list of all remote branches/tags...

[...]
# Runs twice with Sphinx-warnings that we see with normal runs
[...]

copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 27 warnings.

The HTML pages are in ../../../../tmp/tmplibvh55lsphinxcontrib_versioning.

# Freezes

ImportError: cannot import name 'build_main'

Using :

  • sphinx-2.2.0
  • sphinxcontrib-versioning-2.2.1

While running any sphinxcontrib-versioning command, I got :

$ sphinx-versioning build --help

...
File "~/.virtualenvs/docs-temp/lib/python3.6/site-packages/sphinxcontrib/versioning/sphinx_.py", line 9, in <module>
    from sphinx import application, build_main, locale
ImportError: cannot import name 'build_main'

It seems like a wrong module call because build_main is not in sphinx package but it can be called from module sphinx.cmd.build.

Indeed, when I manually modify as below :

# versioning/sphinx_.py

from sphinx import build_main              # old line
from sphinx.cmd.build import build_main    # new line

everything seems to go well.

Sphinx 1.6.1 compatibility

Yesterday, on May 16th, sphinx 1.6.1 was released. sphixcontrib-versioning does not work with that version of sphinx, since the StandaloneHTMLBuilder does not have the default_sidebars attribute anymore, so it fails on AttributeError:

=> Pre-running Sphinx to collect versions' master_doc and other info.
Running Sphinx v1.6.1
loading translations [cs]... done
loading pickled environment... not yet created

Exception occurred:
  File "/home/zegklitz/sandbox/sphinxversioning-env/lib/python3.5/site-packages/sphinxcontrib/versioning/sphinx_.py", line 60, in builder_inited
    app.config.html_sidebars['**'] = StandaloneHTMLBuilder.default_sidebars + ['versions.html']
AttributeError: type object 'StandaloneHTMLBuilder' has no attribute 'default_sidebars'
The full traceback has been saved in /tmp/sphinx-err-hnfq1qko.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-1:
Traceback (most recent call last):
  File "/usr/lib/python3.5/multiprocessing/process.py", line 249, in _bootstrap
    self.run()
  File "/usr/lib/python3.5/multiprocessing/process.py", line 93, in run
    self._target(*self._args, **self._kwargs)
  File "/home/zegklitz/sandbox/sphinxversioning-env/lib/python3.5/site-packages/sphinxcontrib/versioning/sphinx_.py", line 204, in _build
    raise SphinxError
sphinx.errors.SphinxError
=> sphinx-build failed for branch/tag: feature/sdgraph2
Failure.

There are probably more things that went off-rails, this is just the first one that comes up. It works with sphinx 1.5.6 just fine.

The best option would be to make it compatible with 1.6.1. But, fixing it or not, it would be wise to indicate with which sphinx versions does sphinxcontrib-versioning work. It took me quite a lot of digging in the sphinx files and changelogs until I found the source of the issue.

required git version is not specified

I cannot run the application on at least RHEL7 with git version 1.8.3.1.

00:00:07.461 2016-12-13 13:08:59,411 52058 DEBUG    sphinxcontrib.versioning.routines        {"output": "fatal: unrecognized argument: --no-patch\n", "code": 128, "command": ["git", "show", "--no-patch", "--pretty=format:%ct", .... ], "cwd": "..."}

Installing and activated the git19 scl environment appears to address this.

Improve REL_SOURCE description

Hi, thanks for doing this, it's really useful!

Just a suggestion:

I was trying to generate the docs using:

sphinx-versioning build docs docs/build/html

But I was getting...

=> No docs found in any remote branch/tag. Nothing to do.

I couldn't fix it until I read the source code and realized that REL_SOURCE looks for the sphinx conf.py file to determine if the tag/branch has docs or not, but the description for REL_SOURCE in the build command says this:

 REL_SOURCE is the path to the docs directory relative to the git root. If
  the source directory has moved around between git tags you can specify
  additional directories.

I would be better to explain that the docs are found by using the conf.py cause it may be in other places, for example I have mine in docs/source/

Building on windows: tar falls over trying to chdir to tempdir via -C

I leap in where angels fear to tread.

Attempting to use sphinx-versioning on Windows (both native and cygwin). My first problem was that the pipe of git archive ... | tar -C was failing. The command with arguments as given worked okay from the command line, but from within Python, tar was falling over trying to chdir to the temp dir. I got past that by patching thusly to let Python set the cwd instead of relying on tar:

In git.py : export

    git_command = ['git', 'archive', '--format=tar', commit, '--output='+os.path.join(temp_dir,'foo.tar')]
    # Run commands.
    run_command(local_root, git_command, piped=None)
    run_command(temp_dir, ['tar', '-x', '-f', 'foo.tar'], piped=None)
    os.chdir(local_root)

My python is nonexistent so I submit the gist of the idea here only. (foo.tar is madness? os.chdir may not be necessary?)

Test with libraries with removed features.

Make sure docs that import from the project don't break when features are removed. Example: v1.0.0 of a Sphinx extension has .. customDirective: and the docs use it as an example. Then v2.0.0 it was renamed to .. custom_directive and the docs in that version were updated. Make sure v1.0.0 still builds.

Might need to use inheriting virtualenvs: http://stackoverflow.com/questions/12079607/make-virtualenv-inherit-specific-packages-from-your-global-site-packages

Set the Tempdir location

Hey there
we have a little problem with the temp directory on windows 10

we use a docker container (base on win 10) cause we have some windows only python modules in use 😞

if we call the sphinx cmd, the git branches will be checked out under
C:\Users\ContainerAdministrator\AppData\Local\Temp\tmptqij_z1usphinxcontrib_versioning\1f30ec999f942f8b3de8bc24c8d4b25b3642132e\

this is a really long path (136 / 255) and we cant build the docs, because the working dir (subdirs) fills the rest of the path length
=> FileNotFoundError

can you add an option flag to set the "dir" arg in the "tempfile.mkdtemp" to None
then i can use the TMPDIR env var to set my own temdir location

Only push master and tags

Can a flag be added so the push command only pushes the master branch and git tags? In my case I have no reason to have other branches in live documentation and it just adds clutter.

how to use in the right way?

Hi,

I do have a test project with a "doc" folder. In the doc folder I do have a sphinx build under "doc\build\html".

Then I run:

sphinx-versioning build -r master doc doc/build/html

And I get:

=> Gathering info about the remote git repository...
=> Getting list of all remote branches/tags...
=> Found: master v1.0 v1.1 v1.2
=> With docs:
=> No docs found in any remote branch/tag. Nothing to do.
Failure.

So what´s wrong here i read the help but did not find the error.

many thanks

Failed to get dates for all remote commits

this is the error that i get while trying to build the versions! :)
"Failed to get dates for all remote commits"

=> Reading config from source/conf.py...
Running Sphinx v1.6.3
loading pickled environment... not yet created

Exception occurred:
File "/home/senaps/Projects/documents/testversion/env/lib/python2.7/site-packages/sphinxcontrib/versioning/sphinx_.py", line 60, in builder_inited
app.config.html_sidebars['**'] = StandaloneHTMLBuilder.default_sidebars + ['versions.html']
AttributeError: type object 'StandaloneHTMLBuilder' has no attribute 'default_sidebars'
The full traceback has been saved in /tmp/sphinx-err-0FisJh.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-1:
Traceback (most recent call last):
File "/usr/lib64/python2.7/multiprocessing/process.py", line 258, in _bootstrap
self.run()
File "/usr/lib64/python2.7/multiprocessing/process.py", line 114, in run
self._target(*self._args, **self.kwargs)
File "/home/senaps/Projects/documents/testversion/env/lib/python2.7/site-packages/sphinxcontrib/versioning/sphinx
.py", line 219, in _read_config
build(argv, config, Versions(list()), current_name, False)
File "/home/senaps/Projects/documents/testversion/env/lib/python2.7/site-packages/sphinxcontrib/versioning/sphinx
.py", line 204, in _build
raise SphinxError
SphinxError
=> sphinx-build failed for branch/tag while reading config:
=> Unable to read file, continuing with only CLI args.
=> Gathering info about the remote git repository...
=> Getting list of all remote branches/tags...
Username for 'http://': maysam
Password for 'http://maysam@':
=> Found: feature master 1.0.0
=> Failed to get dates for all remote commits.

by the way, no log was generated in tmp/

banner.css isn't added

Using sphinxcontrib-versioning 2.1.3 (upgraded from 2.0.0)

config.py

scv_show_banner = True
scv_banner_greatest_tag = True
scv_whitelist_branches = ('master',)
scv_grm_exclude = ('.gitignore', '.nojekyll', 'README.rst')
scv_sort = ('semver',)

Command Used

sphinx-versioning push docs gh-pages . -- -W

The banner template is rendered and injected fine but the banner.css doesn't get added.

Fail to build with Sphinx > 1.6.0

Commit e8e63b1e9968abbaff46ddd7917d2b53cb505276 in Sphinx removed sphinx.builders.html.StandaloneHTMLBuilder.default_sidebars so build now fails with:

Exception occurred:
  File "/Users/jd/Source/gnocchi/.tox/docs-gnocchi.xyz/lib/python2.7/site-packages/sphinxcontrib/versioning/sphinx_.py", line 60, in builder_inited
    app.config.html_sidebars['**'] = StandaloneHTMLBuilder.default_sidebars + ['versions.html']
AttributeError: type object 'StandaloneHTMLBuilder' has no attribute 'default_sidebars'

Version number doesn't change

I used the fork of @leokoppel to generate the documentation, when I had installed that version of Sphinxcontrib-versioning I ran the following command:
sphinx-versioning build docs/source/ docs/build/html

When I got the documentation, I opened it in my browser, everything was good, but when I tried to change between versions I saw the version numbers didn't change, the rest was fine.

With version numbers I mean that we use the |version| Sphinx replacement, and apparently it is always using the current/latest version instead of the actual version that is supposed to be used.

Follow the next steps to reproduce it:

git clone https://github.com/opensistemas-hub/osbrain.git
cd osbrain
python3.6 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pip install git+https://github.com/leokoppel/sphinxcontrib-versioning.git
sphinx-versioning build docs/source/ docs/build/html

Open the documentation in your browser and try to change between versions.

Somebody knows why the numbers don't change?

html_last_updated_fmt in conf.py causes build failure

When using sphinx-versioning with html_last_updated_fmt = '' in my conf.py file, the following crash occurs. It appears that sphinx-versioning is attempting to call the format_date function with an extra argument. This could be related to #39.

# Sphinx version: 1.6.5
# Python version: 3.6.3 (CPython)
# Docutils version: 0.14 
# Jinja2 version: 2.9.6
# Last messages:
#   checking consistency...
#   
#   done
#   
#   preparing documents...
#   
#   done
#   
#   writing output... [ 20%] index
#   
# Loaded extensions:
#   alabaster (0.7.10) from /usr/local/lib/python3.6/site-packages/alabaster/__init__.py
#   sphinx.ext.todo (1.6.5) from /usr/local/lib/python3.6/site-packages/sphinx/ext/todo.py
#   sphinx.ext.githubpages (1.6.5) from /usr/local/lib/python3.6/site-packages/sphinx/ext/githubpages.py
#   sphinxcontrib.versioning.sphinx_ (2.2.1) from /usr/local/Cellar/python3/3.6.3/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/sphinxcontrib/versioning/sphinx_.py
Traceback (most recent call last):
  File "/usr/local/lib/python3.6/site-packages/sphinx/cmdline.py", line 306, in main
    app.build(opts.force_all, filenames)
  File "/usr/local/lib/python3.6/site-packages/sphinx/application.py", line 339, in build
    self.builder.build_update()
  File "/usr/local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 331, in build_update
    'out of date' % len(to_build))
  File "/usr/local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 397, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 434, in write
    self._write_serial(sorted(docnames))
  File "/usr/local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 443, in _write_serial
    self.write_doc(docname, doctree)
  File "/usr/local/lib/python3.6/site-packages/sphinx/builders/html.py", line 561, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/usr/local/lib/python3.6/site-packages/sphinx/builders/html.py", line 949, in handle_page
    templatename, ctx, event_arg)
  File "/usr/local/lib/python3.6/site-packages/sphinx/application.py", line 493, in emit_firstresult
    return self.events.emit_firstresult(event, self, *args)
  File "/usr/local/lib/python3.6/site-packages/sphinx/events.py", line 84, in emit_firstresult
    for result in self.emit(name, *args):
  File "/usr/local/lib/python3.6/site-packages/sphinx/events.py", line 79, in emit
    results.append(callback(*args))
  File "/usr/local/Cellar/python3/3.6.3/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/sphinxcontrib/versioning/sphinx_.py", line 134, in html_page_context
    context['last_updated'] = format_date(lufmt, mtime, language=app.config.language, warn=app.warn)
TypeError: format_date() got an unexpected keyword argument 'warn'

Support other output formats

It would be nice to be able to build the documentation in other formats (PDF, EPUB) and make them available from the sidebar as in ReadTheDocs.

Load settings from local conf.py.

Things are gonna get too complicated for docopt once I ship the non-root-ref banner in #13. Implement more advanced settings in the local (non-remote, non-committed) conf.py and use read_config() to read it.

Look for the first available conf.py in REL_SOURCEs.

Sphinx-versioning and Setuptools integration

Thanks for an awesome and very useful project!

I have one issue that keeps creeping up. I noticed that sphinx-versioning copies the source code directory to a temporary directory, and then runs sphinx-build. Some projects do not exhibit a working run-time directory structure until setup.py is run and the components are built. In this case, if you copy the source directory, many local imports will fail. For example, my Python package has large C/C++ components with Python classes auto-generated in this process. A much more rudimentary example would be projects that use setuptools to generate a version.py that is then imported locally in __init__.py.

Can you offer an option to build each branch via setup.py? Something along the lines of:

sphinx-versioning --build-cmd `python setup.py build install --prefix $prefixdir`

where $prefixdir is a temp prefix directory that sphinx-versioning runs sphinx-build against for each branch?

Adding support for integration with setuptools will make sphinx-versioning work out of the box with a wider variety of Python projects.

"IndexError: list index out of range" crash in case of big merge commits are in the git tree

Sometimes I'm getting errors like this:

Traceback (most recent call last):
  File "/Users/aivus/envs/oro-doc-version/bin/sphinx-versioning", line 11, in <module>
    load_entry_point('sphinxcontrib-versioning', 'console_scripts', 'sphinx-versioning')()
  File "/Users/aivus/envs/oro-doc-version/lib/python2.7/site-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/Users/aivus/projects/sphinxcontrib-versioning2/sphinxcontrib/versioning/__main__.py", line 78, in main
    return super(ClickGroup, self).main(args=argv, *args, **kwargs)
  File "/Users/aivus/envs/oro-doc-version/lib/python2.7/site-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "/Users/aivus/projects/sphinxcontrib-versioning2/sphinxcontrib/versioning/__main__.py", line 89, in invoke
    return super(ClickGroup, self).invoke(ctx)
  File "/Users/aivus/envs/oro-doc-version/lib/python2.7/site-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/aivus/envs/oro-doc-version/lib/python2.7/site-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/aivus/envs/oro-doc-version/lib/python2.7/site-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/Users/aivus/envs/oro-doc-version/lib/python2.7/site-packages/click/decorators.py", line 64, in new_func
    return ctx.invoke(f, obj, *args, **kwargs)
  File "/Users/aivus/envs/oro-doc-version/lib/python2.7/site-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/Users/aivus/projects/sphinxcontrib-versioning2/sphinxcontrib/versioning/__main__.py", line 276, in build
    remotes = gather_git_info(config.git_root, conf_rel_paths, config.whitelist_branches, config.whitelist_tags)
  File "/Users/aivus/projects/sphinxcontrib-versioning2/sphinxcontrib/versioning/routines.py", line 66, in gather_git_info
    dates_paths = filter_and_date(root, conf_rel_paths, (i[0] for i in remotes))
  File "/Users/aivus/projects/sphinxcontrib-versioning2/sphinxcontrib/versioning/git.py", line 246, in filter_and_date
    dates_paths[commit][0] = timestamps[i]
IndexError: list index out of range

It's caused by the output of the git command

command_prefix = ['git', 'show', '--no-patch', '--pretty=format:%ct']

and this command returns:

1469536315
1562067662
1564053167
1565885343warning: inexact rename detection was skipped due to too many files.
warning: you may want to set your diff.renameLimit variable to at least 2904 and retry the command.

1534772109warning: inexact rename detection was skipped due to too many files.
warning: you may want to set your diff.renameLimit variable to at least 2904 and retry the command.

1471512478warning: inexact rename detection was skipped due to too many files.
warning: you may want to set your diff.renameLimit variable to at least 2904 and retry the command.

1512992270warning: inexact rename detection was skipped due to too many files.
warning: you may want to set your diff.renameLimit variable to at least 2904 and retry the command.

1564866513warning: inexact rename detection was skipped due to too many files.
warning: you may want to set your diff.renameLimit variable to at least 2904 and retry the command.

1558289348warning: inexact rename detection was skipped due to too many files.
warning: you may want to set your diff.renameLimit variable to at least 2904 and retry the command.

1475080037
1458561908
1549283009
1471256827
1565886066
1466433308
1536179026
1472121849
1562321286
1565824289
1558624388
1562067501
1468573872
1563360646
1470395248
1539976798
1505294206
1565009621
1564058239
1565594111
1565888192
1565888350
1565888224
1564761073
1559229466

It can be fixed by removing $ from this regexp:

RE_UNIX_TIME = re.compile(r'^\d{10}$', re.MULTILINE)

Regexp verification:
https://regex101.com/r/Lz0Y8I/1

Building on windows: locks up on sphinx build to read_config

It unpacks the tar for my chosen version and gets to "partially running sphinx-build to read configuration for: master".

Then it blocks-waiting on sphinx_.py : read_config, in the child.join() invocation. (Could this do with a timeout in there to help it clean up after failure?)

From what I can see in the tmp directories, the .doctrees look like they're all made correctly (assuming this is what's meant to happen?). Sphinx reports: sources read 100%.

I realise that it's not returning after the call into the Sphinx api, so not sure how much you can do to fix what's going. Let me know if I can send log files/config/etc to help out.

Same results on Windows native or via cygwin.

Error when running build

I get the following error when trying to run this program:

sh-3.2# sphinx-versioning build -r 'v3.0' docs/ docs/_build/html/
=> Reading config from docs/conf.py...
/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py:202: RemovedInSphinx20Warning: `sphinx.build_main()` has moved to `sphinx.cmd.build.build_main()`.
  result = build_main(argv)
Running Sphinx v1.8.2

Exception occurred:
  File "/Library/Python/2.7/site-packages/sphinx/config.py", line 204, in read
    return cls(namespace, overrides or {})
TypeError: __init__() takes exactly 5 arguments (3 given)
The full traceback has been saved in /tmp/sphinx-err-jLv6Vi.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-1:
Traceback (most recent call last):
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/multiprocessing/process.py", line 258, in _bootstrap
    self.run()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/multiprocessing/process.py", line 114, in run
    self._target(*self._args, **self._kwargs)
  File "/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py", line 219, in _read_config
    _build(argv, config, Versions(list()), current_name, False)
  File "/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py", line 204, in _build
    raise SphinxError
SphinxError
=> sphinx-build failed for branch/tag while reading config: <local>
=> Unable to read file, continuing with only CLI args.
=> Gathering info about the remote git repository...
=> Getting list of all remote branches/tags...
=> Found: master v3.0 2.1 3.0
=> With docs: master
=> Root ref v3.0 not found in: master
Failure.
sh-3.2# git branch
* master
  v3.0
sh-3.2# git checkout -b v2.0
Switched to a new branch 'v2.0'
sh-3.2# git status
On branch v2.0
nothing to commit, working tree clean
sh-3.2# git push origin v2.0
Total 0 (delta 0), reused 0 (delta 0)
remote:
remote: To create a merge request for v2.0, visit:
remote:   https://git.nucleos.com/portablecloud/docs/api-internal/merge_requests/new?merge_request%5Bsource_branch%5D=v2.0
remote:
To git.nucleos.com:portablecloud/docs/api-internal.git
 * [new branch]      v2.0 -> v2.0
sh-3.2# git status
On branch v2.0
nothing to commit, working tree clean
sh-3.2# sphinx-versioning build -r 'v3.0' docs/ docs/_build/html/
=> Reading config from docs/conf.py...
/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py:202: RemovedInSphinx20Warning: `sphinx.build_main()` has moved to `sphinx.cmd.build.build_main()`.
  result = build_main(argv)
Running Sphinx v1.8.2

Exception occurred:
  File "/Library/Python/2.7/site-packages/sphinx/config.py", line 204, in read
    return cls(namespace, overrides or {})
TypeError: __init__() takes exactly 5 arguments (3 given)
The full traceback has been saved in /tmp/sphinx-err-5cAybs.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-1:
Traceback (most recent call last):
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/multiprocessing/process.py", line 258, in _bootstrap
    self.run()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/multiprocessing/process.py", line 114, in run
    self._target(*self._args, **self._kwargs)
  File "/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py", line 219, in _read_config
    _build(argv, config, Versions(list()), current_name, False)
  File "/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py", line 204, in _build
    raise SphinxError
SphinxError
=> sphinx-build failed for branch/tag while reading config: <local>
=> Unable to read file, continuing with only CLI args.
=> Gathering info about the remote git repository...
=> Getting list of all remote branches/tags...
=> Found: master v2.0 v3.0 2.1 3.0
=> With docs: master v2.0
=> Root ref v3.0 not found in: master v2.0
Failure.
sh-3.2# sphinx-versioning build -r 'v2.0' docs/ docs/_build/html/
=> Reading config from docs/conf.py...
/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py:202: RemovedInSphinx20Warning: `sphinx.build_main()` has moved to `sphinx.cmd.build.build_main()`.
  result = build_main(argv)
Running Sphinx v1.8.2

Exception occurred:
  File "/Library/Python/2.7/site-packages/sphinx/config.py", line 204, in read
    return cls(namespace, overrides or {})
TypeError: __init__() takes exactly 5 arguments (3 given)
The full traceback has been saved in /tmp/sphinx-err-i2yAWf.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-1:
Traceback (most recent call last):
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/multiprocessing/process.py", line 258, in _bootstrap
    self.run()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/multiprocessing/process.py", line 114, in run
    self._target(*self._args, **self._kwargs)
  File "/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py", line 219, in _read_config
    _build(argv, config, Versions(list()), current_name, False)
  File "/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py", line 204, in _build
    raise SphinxError
SphinxError
=> sphinx-build failed for branch/tag while reading config: <local>
=> Unable to read file, continuing with only CLI args.
=> Gathering info about the remote git repository...
=> Getting list of all remote branches/tags...
=> Found: master v2.0 v3.0 2.1 3.0
=> With docs: master v2.0
=> Root ref is: v2.0
=> Pre-running Sphinx to collect versions' master_doc and other info.
/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py:202: RemovedInSphinx20Warning: `sphinx.build_main()` has moved to `sphinx.cmd.build.build_main()`.
  result = build_main(argv)
Running Sphinx v1.8.2

Exception occurred:
  File "/Library/Python/2.7/site-packages/sphinx/config.py", line 204, in read
    return cls(namespace, overrides or {})
TypeError: __init__() takes exactly 5 arguments (3 given)
The full traceback has been saved in /tmp/sphinx-err-4o1NJZ.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 "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/multiprocessing/process.py", line 258, in _bootstrap
    self.run()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/multiprocessing/process.py", line 114, in run
    self._target(*self._args, **self._kwargs)
  File "/Library/Python/2.7/site-packages/sphinxcontrib/versioning/sphinx_.py", line 204, in _build
    raise SphinxError
SphinxError
=> sphinx-build failed for branch/tag: v2.0
Failure.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.