Skip to content
Snippets Groups Projects
Commit 0b59b0a7 authored by André Anjos's avatar André Anjos :speech_balloon:
Browse files

[doc] Updates with latest trends from bob/bob.devtools; Make use of... 

[doc] Updates with latest trends from bob/bob.devtools;  Make use of bob.extension to find what to link to user guides
parent 945a6c3b
No related branches found
No related tags found
1 merge request!272Update CI and documentation linking
Hide whitespace changes
Inline Side-by-side
doc/admin/conf.py
+ 46
− 36
View file @ 0b59b0a7
......@@ -50,12 +50,6 @@ extensions = [
'sphinxcontrib.programoutput',
]
import sphinx
if sphinx.__version__ >= "1.4.1":
extensions.append('sphinx.ext.imgmath')
else:
extensions.append('sphinx.ext.pngmath')
# Always includes todos
todo_include_todos = True
......@@ -63,7 +57,7 @@ todo_include_todos = True
numfig = True
# If we are on OSX, the 'dvipng' path maybe different
dvipng_osx = '/opt/local/libexec/texlive/binaries/dvipng'
dvipng_osx = '/Library/TeX/texbin/dvipng'
if os.path.exists(dvipng_osx): pngmath_dvipng = dvipng_osx
# Add any paths that contain templates here, relative to this directory.
......@@ -293,35 +287,51 @@ texinfo_documents = [
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
def smaller_than(v1, v2):
"""Compares scipy/numpy version numbers"""
c1 = v1.split('.')
c2 = v2.split('.')[:len(c1)] #clip to the compared version
for i, k in enumerate(c2):
n1 = c1[i]
n2 = c2[i]
try:
n1 = int(n1)
n2 = int(n2)
except ValueError:
n1 = str(n1)
n2 = str(n2)
if n1 > n2: return False
return True
# Some name mangling to find the correct sphinx manuals for some packages
numpy_version = __import__('numpy').version.version
if smaller_than(numpy_version, '1.5.z'):
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.x'
else:
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.0'
numpy_manual = 'http://docs.scipy.org/doc/numpy-%s/' % numpy_version
# Default processing flags for sphinx
autoclass_content = 'class'
autodoc_member_order = 'bysource'
autodoc_default_flags = [
'members',
'undoc-members',
'show-inheritance',
]
if not 'BOB_DOCUMENTATION_SERVER' in os.environ:
# notice we need to overwrite this for BEAT projects - defaults from Bob are
# not OK
os.environ['BOB_DOCUMENTATION_SERVER'] = "https://www.idiap.ch/software/beat/docs/beat/%(name)s/%(version)s/|https://www.idiap.ch/software/beat/docs/beat/%(name)s/master/"
# For inter-documentation mapping:
intersphinx_mapping = {
'http://docs.python.org/%d.%d/' % sys.version_info[:2]: None,
numpy_manual: None,
'http://matplotlib.sourceforge.net/': None,
}
from bob.extension.utils import link_documentation, load_requirements
sphinx_requirements = "extra-intersphinx.txt"
if os.path.exists(sphinx_requirements):
intersphinx_mapping = link_documentation(
additional_packages=['python','numpy'] + \
load_requirements(sphinx_requirements))
else:
intersphinx_mapping = link_documentation()
# Adds simplejson, pyzmq links
intersphinx_mapping['http://simplejson.readthedocs.io/en/stable/'] = None
# We want to remove all private (i.e. _. or __.__) members
# that are not in the list of accepted functions
accepted_private_functions = ['__array__']
def member_function_test(app, what, name, obj, skip, options):
# test if we have a private function
if len(name) > 1 and name[0] == '_':
# test if this private function should be allowed
if name not in accepted_private_functions:
# omit private functions that are not in the list of accepted private
# functions
return skip
else:
# test if the method is documented
if not hasattr(obj, '__doc__') or not obj.__doc__:
return skip
return False
def setup(app):
app.connect('autodoc-skip-member', member_function_test)
doc/api/conf.py
+ 40
− 16
View file @ 0b59b0a7
......@@ -27,8 +27,6 @@
import os
import sys
import glob
import pkg_resources
# If extensions (or modules to document with autodoc) are in another directory,
......@@ -65,12 +63,6 @@ extensions = [
'sphinxcontrib.httpdomain',
]
import sphinx
if sphinx.__version__ >= "1.4.1":
extensions.append('sphinx.ext.imgmath')
else:
extensions.append('sphinx.ext.pngmath')
# Always includes todos
todo_include_todos = True
......@@ -298,6 +290,7 @@ man_pages = [(
1,
)]
# Default processing flags for sphinx
autoclass_content = 'class'
autodoc_member_order = 'bysource'
......@@ -307,13 +300,44 @@ autodoc_default_flags = [
'show-inheritance',
]
python_version = '.'.join(str(k) for k in sys.version_info[0:2])
python_link = 'http://docs.python.org/' + python_version + '/'
numpy_link = 'http://docs.scipy.org/doc/numpy/'
intersphinx_mapping = dict(
python=(python_link, None),
numpy=(numpy_link, None),
)
if not 'BOB_DOCUMENTATION_SERVER' in os.environ:
# notice we need to overwrite this for BEAT projects - defaults from Bob are
# not OK
os.environ['BOB_DOCUMENTATION_SERVER'] = "https://www.idiap.ch/software/beat/docs/beat/%(name)s/%(version)s/|https://www.idiap.ch/software/beat/docs/beat/%(name)s/master/"
# For inter-documentation mapping:
from bob.extension.utils import link_documentation, load_requirements
sphinx_requirements = "extra-intersphinx.txt"
if os.path.exists(sphinx_requirements):
intersphinx_mapping = link_documentation(
additional_packages=['python','numpy'] + \
load_requirements(sphinx_requirements))
else:
intersphinx_mapping = link_documentation()
# Adds simplejson, pyzmq links
intersphinx_mapping['http://simplejson.readthedocs.io/en/stable/'] = None
# We want to remove all private (i.e. _. or __.__) members
# that are not in the list of accepted functions
accepted_private_functions = ['__array__']
def member_function_test(app, what, name, obj, skip, options):
# test if we have a private function
if len(name) > 1 and name[0] == '_':
# test if this private function should be allowed
if name not in accepted_private_functions:
# omit private functions that are not in the list of accepted private
# functions
return skip
else:
# test if the method is documented
if not hasattr(obj, '__doc__') or not obj.__doc__:
return skip
return False
def setup(app):
pass
app.connect('autodoc-skip-member', member_function_test)
doc/conf.py
+ 32
− 82
View file @ 0b59b0a7
......@@ -25,11 +25,10 @@
# #
###############################################################################
import os
import sys
import pkg_resources
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
......@@ -50,20 +49,36 @@ extensions = [
'sphinxcontrib.programoutput',
]
import sphinx
if sphinx.__version__ >= "1.4.1":
extensions.append('sphinx.ext.imgmath')
else:
extensions.append('sphinx.ext.pngmath')
# Be picky about warnings
nitpicky = True
# Ignores stuff we can't easily resolve on other project's sphinx manuals
nitpick_ignore = []
# Allows the user to override warnings from a separate file
if os.path.exists('nitpick-exceptions.txt'):
for line in open('nitpick-exceptions.txt'):
if line.strip() == "" or line.startswith("#"):
continue
dtype, target = line.split(None, 1)
target = target.strip()
try: # python 2.x
target = unicode(target)
except NameError:
pass
nitpick_ignore.append((dtype, target))
# Always includes todos
todo_include_todos = True
# Generates auto-summary automatically
autosummary_generate = True
# Create numbers on figures with captions
numfig = True
# If we are on OSX, the 'dvipng' path maybe different
dvipng_osx = '/opt/local/libexec/texlive/binaries/dvipng'
dvipng_osx = '/Library/TeX/texbin/dvipng'
if os.path.exists(dvipng_osx): pngmath_dvipng = dvipng_osx
# Add any paths that contain templates here, relative to this directory.
......@@ -80,18 +95,12 @@ master_doc = 'index'
top_module = 'beat'
# General information about the project.
project = u'BEAT Web Application' # (%s)' % top_module
authors = u'Idiap Research Institute'
project = u'beat.cmdline'
import time
copyright = u'%s, Idiap Research Institute, Switzerland' % time.strftime('%Y')
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
# Grab the setup entry
distribution = pkg_resources.require('beat.web')[0]
distribution = pkg_resources.require(project)[0]
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
......@@ -136,6 +145,11 @@ pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# Some variables which are useful for generated material
project_variable = project.replace('.', '_')
short_description = u'Biometrics Evaluation and Testing Platform (Web Modules)'
owner = [u'Idiap Research Institute']
# -- Autodoc settings ---------------------------------------------------
......@@ -220,7 +234,7 @@ html_theme = 'sphinx_rtd_theme'
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'BEATdoc'
htmlhelp_basename = project_variable + u'_doc'
# -- Options for LaTeX output --------------------------------------------------
......@@ -261,67 +275,3 @@ latex_documents = [
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, top_module, project, authors, 1),
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, top_module, project, authors, top_module, project, 'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
def smaller_than(v1, v2):
"""Compares scipy/numpy version numbers"""
c1 = v1.split('.')
c2 = v2.split('.')[:len(c1)] #clip to the compared version
for i, k in enumerate(c2):
n1 = c1[i]
n2 = c2[i]
try:
n1 = int(n1)
n2 = int(n2)
except ValueError:
n1 = str(n1)
n2 = str(n2)
if n1 > n2: return False
return True
# Some name mangling to find the correct sphinx manuals for some packages
numpy_version = __import__('numpy').version.version
if smaller_than(numpy_version, '1.5.z'):
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.x'
else:
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.0'
numpy_manual = 'http://docs.scipy.org/doc/numpy-%s/' % numpy_version
# For inter-documentation mapping:
intersphinx_mapping = {
'http://docs.python.org/%d.%d/' % sys.version_info[:2]: None,
numpy_manual: None,
'http://matplotlib.sourceforge.net/': None,
}
doc/user/conf.py
+ 46
− 17
View file @ 0b59b0a7
......@@ -27,8 +27,6 @@
import os
import sys
import glob
import pkg_resources
# If extensions (or modules to document with autodoc) are in another directory,
......@@ -56,12 +54,6 @@ extensions = [
'sphinx.ext.viewcode',
]
import sphinx
if sphinx.__version__ >= "1.4.1":
extensions.append('sphinx.ext.imgmath')
else:
extensions.append('sphinx.ext.pngmath')
# Always includes todos
todo_include_todos = True
......@@ -72,7 +64,7 @@ numfig = True
autosummary_generate = True
# If we are on OSX, the 'dvipng' path maybe different
dvipng_osx = '/opt/local/libexec/texlive/binaries/dvipng'
dvipng_osx = '/Library/TeX/texbin/dvipng'
if os.path.exists(dvipng_osx): pngmath_dvipng = dvipng_osx
# Add any paths that contain templates here, relative to this directory.
......@@ -295,13 +287,50 @@ autodoc_default_flags = [
'show-inheritance',
]
python_version = '.'.join(str(k) for k in sys.version_info[0:2])
python_link = 'http://docs.python.org/' + python_version + '/'
numpy_link = 'http://docs.scipy.org/doc/numpy/'
intersphinx_mapping = dict(
python=(python_link, None),
numpy=(numpy_link, None),
)
if not 'BOB_DOCUMENTATION_SERVER' in os.environ:
# notice we need to overwrite this for BEAT projects - defaults from Bob are
# not OK
os.environ['BOB_DOCUMENTATION_SERVER'] = "https://www.idiap.ch/software/beat/docs/beat/%(name)s/%(version)s/|https://www.idiap.ch/software/beat/docs/beat/%(name)s/master/"
# For inter-documentation mapping:
from bob.extension.utils import link_documentation, load_requirements
sphinx_requirements = "extra-intersphinx.txt"
if os.path.exists(sphinx_requirements):
intersphinx_mapping = link_documentation(
additional_packages=['python','numpy'] + \
load_requirements(sphinx_requirements))
else:
intersphinx_mapping = link_documentation()
# Adds simplejson, pyzmq links
intersphinx_mapping['http://simplejson.readthedocs.io/en/stable/'] = None
# We want to remove all private (i.e. _. or __.__) members
# that are not in the list of accepted functions
accepted_private_functions = ['__array__']
def member_function_test(app, what, name, obj, skip, options):
# test if we have a private function
if len(name) > 1 and name[0] == '_':
# test if this private function should be allowed
if name not in accepted_private_functions:
# omit private functions that are not in the list of accepted private
# functions
return skip
else:
# test if the method is documented
if not hasattr(obj, '__doc__') or not obj.__doc__:
return skip
return False
def setup(app):
pass
app.connect('autodoc-skip-member', member_function_test)
# Default processing flags for sphinx
autoclass_content = 'class'
autodoc_member_order = 'bysource'
autodoc_default_flags = [
'members',
'undoc-members',
'show-inheritance',
]
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment