diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..aee7b78 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,12 @@ +version: 2 + +sphinx: + configuration: docs/conf.py + +formats: + - pdf + +python: + 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 cfaaa9a..dd5f081 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,40 +8,55 @@ # 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 - os.environ['SPHINX_APIDOC_OPTIONS'] = ','.join(['members', - 'undoc-members', - 'inherited-members', - 'show-inheritance']) +# 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(" ")) + cmd_line = cmd_line_template.format(outputdir=output_dir, moduledir=module_dir) + + args = cmd_line.split(" ") + if parse_version(sphinx.__version__) >= parse_version('1.7'): + args = args[1:] -# -- General configuration ----------------------------------------------- + apidoc.main(args) +except Exception as e: + print("Running `sphinx-apidoc` failed!\n{}".format(e)) + +# -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' @@ -50,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. @@ -67,7 +82,7 @@ # General information about the project. project = u'gldas' -copyright = u'2016, TU Wien' +copyright = u'2020, TU Wien' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -116,7 +131,7 @@ # keep_warnings = False -# -- Options for HTML output --------------------------------------------- +# -- Options for HTML output --------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. @@ -125,7 +140,10 @@ # 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 = [] @@ -201,24 +219,24 @@ htmlhelp_basename = 'gldas-doc' -# -- Options for LaTeX output -------------------------------------------- +# -- Options for LaTeX output -------------------------------------------------- latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # 'papersize': 'letterpaper', +# The paper size ('letterpaper' or 'a4paper'). +# 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # 'pointsize': '10pt', +# The font size ('10pt', '11pt' or '12pt'). +# 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # 'preamble': '', +# Additional stuff for the LaTeX preamble. +# 'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'user_guide.tex', u'gldas Documentation', - u'TU Wien', 'manual'), + ('index', 'user_guide.tex', u'gldas Documentation', + u'TU Wien', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -241,14 +259,14 @@ # If false, no module index is generated. # latex_domain_indices = True -# -- External mapping ---------------------------------------------------- +# -- 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