diff --git a/bob/extension/test_utils.py b/bob/extension/test_utils.py
index 73da7428e557aa975aff4f0c517c826a0b0c0541..09c73de22045ad7f681c4657d45570b2d53378cb 100644
--- a/bob/extension/test_utils.py
+++ b/bob/extension/test_utils.py
@@ -191,12 +191,12 @@ package-z
]
# test linkage to pythonhosted.org
- server = "https://pythonhosted.org/%s"
+ server = "https://pythonhosted.org/%s/"
os.environ["BOB_DOCUMENTATION_SERVER"] = server
result = link_documentation(additional_packages, stringio(f))
expected = [
- 'https://docs.python.org/%d.%d' % sys.version_info[:2],
- 'http://matplotlib.org',
+ 'https://docs.python.org/%d.%d/' % sys.version_info[:2],
+ 'http://matplotlib.org/',
'https://setuptools.readthedocs.io/en/latest/',
server % 'bob.extension',
server % 'gridtk',
@@ -205,12 +205,12 @@ package-z
nose.tools.eq_(sorted(result), sorted(expected))
# test idiap server
- server = "https://www.idiap.ch/software/bob/docs/latest/bob/%s/master"
+ server = "https://www.idiap.ch/software/bob/docs/latest/bob/%s/master/"
os.environ["BOB_DOCUMENTATION_SERVER"] = server
result = link_documentation(additional_packages, stringio(f))
expected = [
- 'https://docs.python.org/%d.%d' % sys.version_info[:2],
- 'http://matplotlib.org',
+ 'https://docs.python.org/%d.%d/' % sys.version_info[:2],
+ 'http://matplotlib.org/',
'https://setuptools.readthedocs.io/en/latest/',
server % 'bob.extension',
server % 'gridtk',
diff --git a/bob/extension/utils.py b/bob/extension/utils.py
index 080f50825e7afacb22a77576417492b4dd2b71b8..0eaf07f45b366e72e4ab61f88d88f8d23180b3ec 100644
--- a/bob/extension/utils.py
+++ b/bob/extension/utils.py
@@ -429,66 +429,79 @@ def link_documentation(additional_packages = ['python', 'numpy'], requirements_f
HTTPError = error.HTTPError
URLError = error.URLError
- # collect packages
+
+ # collect packages are automatically included in the list of indexes
packages = []
+ version_re = re.compile(r'\s*[\<\>=]+\s*')
if requirements_file is not None:
- if not isinstance(requirements_file, str) or os.path.exists(requirements_file):
- packages += load_requirements(requirements_file)
+ if not isinstance(requirements_file, str) or \
+ os.path.exists(requirements_file):
+ requirements = load_requirements(requirements_file)
+ packages += [version_re.split(k)[0] for k in requirements]
packages += additional_packages
- # standard documentation: Python
- mapping = {}
- if 'python' in packages:
- python_manual = 'https://docs.python.org/%d.%d' % sys.version_info[:2]
- print ("Adding intersphinx source %s" % python_manual)
- mapping['python'] = (python_manual, None)
- packages = [k for k in packages if k != 'python']
- if 'numpy' in packages:
+ def _add_index(name, addr, packages=packages):
+ """Helper to add a new doc index to the intersphinx catalog
+
+ Parameters:
+
+ name (str): Name of the package that will be added to the catalog
+ addr (str): The URL (except the ``objects.inv`` file), that will be added
+
+ """
+
+ if name in packages:
+ print ("Adding intersphinx source for `%s': %s" % (name, addr))
+ mapping[name] = (addr, None)
+ packages = [k for k in packages if k != name]
+
+
+ def _add_numpy_index():
+ """Helper to add the numpy manual"""
+
try:
import numpy
- numpy_version = numpy.version.version
- if smaller_than(numpy_version, '1.5.z'):
- numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.x'
+ ver = numpy.version.version
+ if smaller_than(ver, '1.5.z'):
+ ver = '.'.join(ver.split('.')[:-1]) + '.x'
else:
- numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.0'
+ ver = '.'.join(ver.split('.')[:-1]) + '.0'
+ _add_index('numpy', 'https://docs.scipy.org/doc/numpy-%s/' % ver)
+
except ImportError:
- numpy_version = '1.9.1'
- numpy_manual = 'https://docs.scipy.org/doc/numpy-%s' % numpy_version
+ _add_index('numpy', 'https://docs.scipy.org/doc/numpy/')
+
- # numpy mapping
- print ("Adding intersphinx source %s" % numpy_manual)
- mapping['numpy'] = (numpy_manual, None)
- packages = [k for k in packages if k != 'numpy']
+ def _add_scipy_index():
+ """Helper to add the scipy manual"""
- if 'scipy' in packages:
try:
import scipy
- scipy_version = scipy.version.version
- if smaller_than(scipy_version, '0.9.0'):
- scipy_version = '.'.join(scipy_version.split('.')[:-1]) + '.x'
+ ver = scipy.version.version
+ if smaller_than(ver, '0.9.0'):
+ ver = '.'.join(ver.split('.')[:-1]) + '.x'
else:
- scipy_version = '.'.join(scipy_version.split('.')[:-1]) + '.0'
+ ver = '.'.join(ver.split('.')[:-1]) + '.0'
+ _add_index('scipy', 'https://docs.scipy.org/doc/scipy-%s/reference/' % ver)
+
except ImportError:
- scipy_version = '0.16.1'
- scipy_manual = 'https://docs.scipy.org/doc/scipy-%s/reference' % scipy_version
+ _add_index('scipy', 'https://docs.scipy.org/doc/scipy/reference/')
- # scipy mapping
- print ("Adding intersphinx source %s" % scipy_manual)
- mapping['scipy'] = (scipy_manual, None)
- packages = [k for k in packages if k != 'scipy']
- if 'matplotlib' in packages:
- matplotlib_manual = "http://matplotlib.org"
- print ("Adding intersphinx source %s" % matplotlib_manual)
- mapping['matplotlib'] = (matplotlib_manual, None)
- packages = [k for k in packages if k != 'matplotlib']
+ mapping = {}
- if 'setuptools' in packages: #get the right url
- setuptools_manual = "https://setuptools.readthedocs.io/en/latest/"
- print ("Adding intersphinx source %s" % setuptools_manual)
- mapping['setuptools'] = (setuptools_manual, None)
- packages = [k for k in packages if k != 'setuptools']
+ # add indexes for common packages used in Bob
+ _add_index('python', 'https://docs.python.org/%d.%d/' % sys.version_info[:2])
+ _add_numpy_index()
+ _add_scipy_index()
+ _add_index('matplotlib', 'http://matplotlib.org/')
+ _add_index('setuptools', 'https://setuptools.readthedocs.io/en/latest/')
+ _add_index('six', 'https://pythonhosted.org/six/')
+ _add_index('sqlalchemy', 'https://docs.sqlalchemy.org/en/latest/')
+ _add_index('docopt', 'http://docopt.readthedocs.io/en/latest/')
+ _add_index('scikit-image', 'http://scikit-image.org/docs/dev/')
+ _add_index('pillow', 'http://pillow.readthedocs.io/en/latest/')
# get the server for the other packages
@@ -502,7 +515,10 @@ def link_documentation(additional_packages = ['python', 'numpy'], requirements_f
# transforms "(file:///path/to/dir https://example.com/dir| http://bla )"
# into ["file:///path/to/dir", "https://example.com/dir", "http://bla"]
# so, trim eventual parenthesis/white-spaces and splits by white space or |
- server = re.split(r'[|\s]+', server.strip('() '))
+ if server.strip():
+ server = re.split(r'[|\s]+', server.strip('() '))
+ else:
+ server = []
# check if the packages have documentation on the server
for p in packages:
diff --git a/doc/guide.rst b/doc/guide.rst
index 4ccb72c9926334ab3dc5cdf5138ad733632a4d25..03f67be741905e7a223b969f90c4825ee31d9e0f 100644
--- a/doc/guide.rst
+++ b/doc/guide.rst
@@ -486,44 +486,46 @@ Here is a set of steps we recommend you follow when releasing a new version of y
In this fictitious representation, the ``master`` branch continue under development, but one can see older branches don't receive much attention anymore.
Here is an example for creating a branch at gitlab (many of our satellite packages are hosted there).
- Let's create a branch called ``1.1``::
+ Let's create a branch called ``1.1``:
.. code-block:: sh
- $ git branch 1.1
- $ git checkout 1.1
- $ git push origin 1.1
+ $ git branch 1.1
+ $ git checkout 1.1
+ $ git push origin 1.1
3. When you decide to release something publicly, we recommend you **tag** the version of the package on your repository, so you have a marker to what code you actually published on PyPI.
- Tagging on gitlab would go like this::
+ Tagging on gitlab would go like this:
.. code-block:: sh
- $ git tag v1.1.0
- $ git push && git push --tags
+ $ git tag v1.1.0
+ $ git push && git push --tags
Notice use prefix tag names with ``v``.
4. Finally, after branching and tagging, it is time for you to publish your new package on PyPI.
- When the package is ready and you have tested it, just do the following::
+ When the package is ready and you have tested it, just do the following:
.. code-block:: sh
- $ ./bin/python setup.py register #if you modified your setup.py or README.rst
- $ ./bin/python setup.py sdist --formats zip upload
+ $ ./bin/python setup.py register #if you modified your setup.py or README.rst
+ $ ./bin/python setup.py sdist --formats zip upload
- .. note::
- You can also check the .zip file that will be uploaded to PyPI before actually uploading it.
- Just call:
+ .. note::
+
+ You can also check the .zip file that will be uploaded to PyPI before
+ actually uploading it. Just call:
.. code-block:: sh
- $ ./bin/python setup.py sdist --formats zip
+ $ ./bin/python setup.py sdist --formats zip
and check what was put into the ``dist`` directory.
.. note::
- To be able to upload a package to PyPI_ you have to register at the web page using a user name and password.
+ To be able to upload a package to PyPI_ you have to register at the web
+ page using a user name and password.
5. Announce the update on the relevant channels.
@@ -536,11 +538,12 @@ More detailed information are given `here <http://pythonhosted.org/an_example_py
.. code-block:: sh
- $ ./bin/python setup.py build_sphinx --source-dir=doc --build-dir=build/doc --all-files
- $ ./bin/python setup.py upload_docs --upload-dir=build/doc/html
+ $ ./bin/python setup.py build_sphinx --source-dir=doc --build-dir=build/doc --all-files
+ $ ./bin/python setup.py upload_docs --upload-dir=build/doc/html
-The link to the documentation will automatically be added to the PyPI page of your package.
-Usually it is a good idea to check the documentation after building and before uploading.
+The link to the documentation will automatically be added to the PyPI page of
+your package. Usually it is a good idea to check the documentation after
+building and before uploading.
Change the Version of your Satellite Package