From b9d62eaf32721c29433fd6128a22a0c659311613 Mon Sep 17 00:00:00 2001 From: Wolfgang Preimesberger Date: Thu, 18 Jun 2020 15:29:04 +0200 Subject: [PATCH] Test different docs setup --- .readthedocs.yml | 9 ++---- docs/conf.py | 63 ++++++++++++++++++++++++++++-------------- docs/requirements.txt | 1 + src/gldas/interface.py | 3 +- 4 files changed, 48 insertions(+), 28 deletions(-) create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml index a277de7..aee7b78 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -7,9 +7,6 @@ formats: - pdf python: - install: - - method: pip - path: . - -conda: - environment: environment.yml \ No newline at end of file + version: 3.7 + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 17a3eca..dd5f081 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,33 +8,53 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import os import sys +import inspect +import shutil + +__location__ = os.path.join(os.getcwd(), os.path.dirname( + inspect.getfile(inspect.currentframe()))) # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -# sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.join(__location__, '../src')) -# -- Hack for ReadTheDocs ------------------------------------------------------ +# -- Run sphinx-apidoc ------------------------------------------------------ # This hack is necessary since RTD does not issue `sphinx-apidoc` before running # `sphinx-build -b html . _build/html`. See Issue: # https://github.com/rtfd/readthedocs.org/issues/1139 # DON'T FORGET: Check the box "Install your project inside a virtualenv using # setup.py install" in the RTD Advanced Settings. -import os -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' -if on_rtd: - import inspect +# Additionally it helps us to avoid running apidoc manually + +try: # for Sphinx >= 1.7 + from sphinx.ext import apidoc +except ImportError: from sphinx import apidoc - __location__ = os.path.join(os.getcwd(), os.path.dirname( - inspect.getfile(inspect.currentframe()))) +output_dir = os.path.join(__location__, "api") +module_dir = os.path.join(__location__, "../src/gldas") +try: + shutil.rmtree(output_dir) +except FileNotFoundError: + pass + +try: + import sphinx + from pkg_resources import parse_version - output_dir = os.path.join(__location__, "../docs/api") - module_dir = os.path.join(__location__, "../gldas") cmd_line_template = "sphinx-apidoc -f -o {outputdir} {moduledir}" cmd_line = cmd_line_template.format(outputdir=output_dir, moduledir=module_dir) - apidoc.main(cmd_line.split(" ")) + + args = cmd_line.split(" ") + if parse_version(sphinx.__version__) >= parse_version('1.7'): + args = args[1:] + + apidoc.main(args) +except Exception as e: + print("Running `sphinx-apidoc` failed!\n{}".format(e)) # -- General configuration ----------------------------------------------------- @@ -45,7 +65,7 @@ # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.autosummary', 'sphinx.ext.viewcode', 'sphinx.ext.coverage', - 'sphinx.ext.doctest', 'sphinx.ext.ifconfig', 'sphinx.ext.pngmath', + 'sphinx.ext.doctest', 'sphinx.ext.ifconfig', 'sphinx.ext.mathjax', 'sphinx.ext.napoleon'] # Add any paths that contain templates here, relative to this directory. @@ -115,12 +135,15 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# html_theme_options = {} +html_theme_options = { + 'sidebar_width': '300px', + 'page_width': '1200px' +} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] @@ -239,11 +262,11 @@ # -- External mapping ------------------------------------------------------------ python_version = '.'.join(map(str, sys.version_info[0:2])) intersphinx_mapping = { - 'sphinx': ('http://sphinx.pocoo.org', None), - 'python': ('http://docs.python.org/' + python_version, None), - 'matplotlib': ('http://matplotlib.sourceforge.net', None), - 'numpy': ('http://docs.scipy.org/doc/numpy', None), + 'sphinx': ('http://www.sphinx-doc.org/en/stable', None), + 'python': ('https://docs.python.org/' + python_version, None), + 'matplotlib': ('https://matplotlib.org', None), + 'numpy': ('https://docs.scipy.org/doc/numpy', None), 'sklearn': ('http://scikit-learn.org/stable', None), 'pandas': ('http://pandas.pydata.org/pandas-docs/stable', None), - 'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None), -} + 'scipy': ('https://docs.scipy.org/doc/scipy/reference', None), +} \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..52b04f2 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +sphinx_rtd_theme \ No newline at end of file diff --git a/src/gldas/interface.py b/src/gldas/interface.py index dbf51a5..fa25966 100644 --- a/src/gldas/interface.py +++ b/src/gldas/interface.py @@ -442,5 +442,4 @@ def __init__(self, ts_path, grid_path=None, **kwargs): grid_path = os.path.join(ts_path, "grid.nc") grid = load_grid(grid_path) - super(GLDASTs, self).__init__(ts_path, grid, **kwargs) - + super(GLDASTs, self).__init__(ts_path, grid, **kwargs) \ No newline at end of file