From d477fe48dd893490a9bb315a8fb57017cfe6389d Mon Sep 17 00:00:00 2001 From: Leonardo Uieda Date: Fri, 17 Jul 2020 14:15:40 +0100 Subject: [PATCH] Format the doc/conf.py file with Black For some reason we weren't formatting this file. Ran black on it and added it to the black and flake8 runs in the main Makefile. Removed the setting of `sys.path` since we're installing the packaged in edit mode so it should be importable without that hack. --- Makefile | 4 +- doc/conf.py | 127 +++++++++++++++++++++++++++++----------------------- 2 files changed, 73 insertions(+), 58 deletions(-) diff --git a/Makefile b/Makefile index e8803891..27a977af 100644 --- a/Makefile +++ b/Makefile @@ -4,8 +4,8 @@ TESTDIR=.tmp-test-dir-with-unique-name PYTEST_ARGS=--cov-config=../.coveragerc --cov-report=term-missing --cov=$(PROJECT) --doctest-modules -v --pyargs PYTEST_MINIMAL_ARGS=-v --pyargs -m minimal LINT_FILES=setup.py $(PROJECT) -BLACK_FILES=setup.py $(PROJECT) examples -FLAKE8_FILES=setup.py $(PROJECT) examples +BLACK_FILES=setup.py $(PROJECT) examples doc/conf.py +FLAKE8_FILES=setup.py $(PROJECT) examples doc/conf.py help: @echo "Commands:" diff --git a/doc/conf.py b/doc/conf.py index 65859702..cc57806a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -6,24 +6,20 @@ import sphinx_gallery from sphinx_gallery.sorting import FileNameSortKey -# Sphinx needs to be able to import the package to use autodoc and get the -# version number -sys.path.append(os.path.pardir) - from rockhound.version import full_version extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.coverage', - 'sphinx.ext.mathjax', - 'sphinx.ext.doctest', - 'sphinx.ext.viewcode', - 'sphinx.ext.extlinks', + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.coverage", + "sphinx.ext.mathjax", + "sphinx.ext.doctest", + "sphinx.ext.viewcode", + "sphinx.ext.extlinks", "sphinx.ext.intersphinx", - 'matplotlib.sphinxext.plot_directive', - 'sphinx.ext.napoleon', - 'sphinx_gallery.gen_gallery', + "matplotlib.sphinxext.plot_directive", + "sphinx.ext.napoleon", + "sphinx_gallery.gen_gallery", ] # intersphinx configuration @@ -39,64 +35,66 @@ # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build autosummary_generate = [] -# Otherwise, the Return parameter list looks different from the Parameters list +# Otherwise, the Return list looks different from the Parameters list napoleon_use_rtype = False -# Otherwise, the Attributes parameter list looks different from the Parameters list +# Otherwise, the Attributes list looks different from the Parameters list napoleon_use_ivar = True sphinx_gallery_conf = { # path to your examples scripts - 'examples_dirs': ['../examples'], + "examples_dirs": ["../examples"], # path where to save gallery generated examples - 'gallery_dirs': ['gallery'], - 'filename_pattern': '\.py', + "gallery_dirs": ["gallery"], + "filename_pattern": r"\.py", # Remove the "Download all examples" button from the top level gallery - 'download_all_examples': False, + "download_all_examples": False, # Sort gallery example by file name instead of number of lines (default) - 'within_subsection_order': FileNameSortKey, + "within_subsection_order": FileNameSortKey, # directory where function granular galleries are stored - 'backreferences_dir': 'api/generated/backreferences', + "backreferences_dir": "api/generated/backreferences", # Modules for which function level galleries are created. In # this case sphinx_gallery and numpy in a tuple of strings. - 'doc_module': 'rockhound', + "doc_module": "rockhound", # Insert links to documentation of objects in the examples - 'reference_url': {'rockhound': None}, + "reference_url": {"rockhound": None}, } # Always show the source code that generates a plot plot_include_source = True -plot_formats = ['png'] +plot_formats = ["png"] # Sphinx project configuration -templates_path = ['_templates'] -exclude_patterns = ['_build', '**.ipynb_checkpoints'] -source_suffix = '.rst' +templates_path = ["_templates"] +exclude_patterns = ["_build", "**.ipynb_checkpoints"] +source_suffix = ".rst" # The encoding of source files. -source_encoding = 'utf-8-sig' -master_doc = 'index' +source_encoding = "utf-8-sig" +master_doc = "index" # General information about the project year = datetime.date.today().year -project = 'RockHound' -copyright = '2018-{}, The RockHound Developers'.format(year) -if len(full_version.split('+')) > 1 or full_version == 'unknown': - version = 'dev' +project = "RockHound" +copyright = "2018-{}, The RockHound Developers".format(year) +if len(full_version.split("+")) > 1 or full_version == "unknown": + version = "dev" else: version = full_version # These enable substitutions using |variable| in the rst files rst_epilog = """ .. |year| replace:: {year} -""".format(year=year) +""".format( + year=year +) -html_last_updated_fmt = '%b %d, %Y' +html_last_updated_fmt = "%b %d, %Y" html_title = project html_short_title = project -html_logo = '' -html_favicon = '_static/favicon.png' -html_static_path = ['_static'] +html_logo = "" +html_favicon = "_static/favicon.png" +html_static_path = ["_static"] html_extra_path = [] -pygments_style = 'default' +pygments_style = "default" add_function_parentheses = False html_show_sourcelink = False html_show_sphinx = True @@ -105,28 +103,45 @@ # Theme config html_theme = "sphinx_rtd_theme" html_theme_options = { - 'logo_only': True, - 'display_version': True, + "logo_only": True, + "display_version": True, } html_context = { - 'menu_links_name': 'Getting help and contributing', - 'menu_links': [ - (' Fatiando a Terra', 'https://www.fatiando.org'), - (' Contributing', 'https://github.com/fatiando/rockhound/blob/master/CONTRIBUTING.md'), - (' Code of Conduct', 'https://github.com/fatiando/rockhound/blob/master/CODE_OF_CONDUCT.md'), - (' Contact', 'https://gitter.im/fatiando/fatiando'), - (' Source Code', 'https://github.com/fatiando/rockhound'), + "menu_links_name": "Getting help and contributing", + "menu_links": [ + ( + ' Fatiando a Terra', + "https://www.fatiando.org", + ), + ( + ' Contributing', + "https://github.com/fatiando/rockhound/blob/master/CONTRIBUTING.md", + ), + ( + ' Code of Conduct', + "https://github.com/fatiando/rockhound/blob/master/CODE_OF_CONDUCT.md", + ), + ( + ' Contact', + "https://gitter.im/fatiando/fatiando", + ), + ( + ' Source Code', + "https://github.com/fatiando/rockhound", + ), ], # Custom variables to enable "Improve this page"" and "Download notebook" # links - 'doc_path': 'doc', - 'galleries': sphinx_gallery_conf['gallery_dirs'], - 'gallery_dir': dict(zip(sphinx_gallery_conf['gallery_dirs'], - sphinx_gallery_conf['examples_dirs'])), - 'github_repo': 'fatiando/rockhound', - 'github_version': 'master', + "doc_path": "doc", + "galleries": sphinx_gallery_conf["gallery_dirs"], + "gallery_dir": dict( + zip(sphinx_gallery_conf["gallery_dirs"], sphinx_gallery_conf["examples_dirs"]) + ), + "github_repo": "fatiando/rockhound", + "github_version": "master", } -# Load the custom CSS files (needs sphinx >= 1.6 for this to work) + def setup(app): + "Load the custom CSS files (needs sphinx >= 1.6 for this to work)" app.add_stylesheet("style.css")