Check and lint sphinx configuration file doc/conf.py (#630)

* Remove the _build/html directory
* Remove unused import
* Use html_css_files to include custom CSS files (needs Sphinx>=1.8)
The old way (the `setup()` function) is difficult to understand.
* Fix linting errors in doc/conf.py
* Check and lint doc/conf.py
* Disable the "no-name-in-module" lint error

Co-authored-by: Wei Ji <[email protected]>

Author: seisman

Makefile

@@ -6,8 +6,8 @@ PYTEST_ARGS=--cov=$(PROJECT) --cov-config=../.coveragerc \
 			--doctest-modules -v --mpl --mpl-results-path=results \
 			--pyargs ${PYTEST_EXTRA}
 BLACK_FILES=$(PROJECT) setup.py doc/conf.py examples
-FLAKE8_FILES=$(PROJECT) setup.py
-LINT_FILES=$(PROJECT) setup.py
+FLAKE8_FILES=$(PROJECT) setup.py doc/conf.py
+LINT_FILES=$(PROJECT) setup.py doc/conf.py
 
 help:
 	@echo "Commands:"

doc/Makefile

@@ -21,7 +21,7 @@ help:
 	@echo "  doctest    run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	rm -rf $(BUILDDIR)/html/*
+	rm -rf $(BUILDDIR)/html
 	rm -rf $(BUILDDIR)/doctrees
 	rm -rf $(BUILDDIR)/linkcheck
 	rm -rf modules

doc/conf.py

@@ -1,12 +1,14 @@
 # -*- coding: utf-8 -*-
-import sys
-import os
-import glob
-import shutil
+"""
+Sphinx documentation configuration file.
+"""
+# pylint: disable=invalid-name
+
 import datetime
-import sphinx_rtd_theme
-import sphinx_gallery
-from sphinx_gallery.sorting import FileNameSortKey, ExplicitOrder
+from sphinx_gallery.sorting import (  # pylint: disable=no-name-in-module
+    FileNameSortKey,
+    ExplicitOrder,
+)
 from pygmt import __version__, __commit__
 from pygmt.sphinx_gallery import PyGMTScraper
 
@@ -91,14 +93,15 @@
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "**.ipynb_checkpoints"]
 source_suffix = ".rst"
+needs_sphinx = "1.8"
 # The encoding of source files.
 source_encoding = "utf-8-sig"
 master_doc = "index"
 
 # General information about the project
 year = datetime.date.today().year
 project = "PyGMT"
-copyright = "2017-{}, The PyGMT Developers.".format(year)
+copyright = f"2017-{year}, The PyGMT Developers."  # pylint: disable=redefined-builtin
 if len(__version__.split("+")) > 1 or __version__ == "unknown":
     version = "dev"
 else:
@@ -118,6 +121,7 @@
 html_logo = ""
 html_favicon = "_static/favicon.png"
 html_static_path = ["_static"]
+html_css_files = ["style.css"]
 html_extra_path = []
 pygments_style = "default"
 add_function_parentheses = False
@@ -129,28 +133,29 @@
 html_theme = "sphinx_rtd_theme"
 html_theme_options = {}
 repository = "GenericMappingTools/pygmt"
-commit_link = f'<a href="https://github.com/GenericMappingTools/pygmt/commit/{ __commit__ }">{ __commit__[:7] }</a>'
+repository_url = "https://github.com/GenericMappingTools/pygmt"
+commit_link = f'<a href="{repository_url}/commit/{ __commit__ }">{ __commit__[:7] }</a>'
 html_context = {
     "menu_links": [
         (
             '<i class="fa fa-users fa-fw"></i> Contributing',
-            "https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md",
+            f"{repository_url}/blob/master/CONTRIBUTING.md",
         ),
         (
             '<i class="fa fa-gavel fa-fw"></i> Code of Conduct',
-            "https://github.com/GenericMappingTools/pygmt/blob/master/CODE_OF_CONDUCT.md",
+            f"{repository_url}/blob/master/CODE_OF_CONDUCT.md",
         ),
         (
             '<i class="fa fa-book fa-fw"></i> License',
-            "https://github.com/GenericMappingTools/pygmt/blob/master/LICENSE.txt",
+            f"{repository_url}/blob/master/LICENSE.txt",
         ),
         (
             '<i class="fa fa-comment fa-fw"></i> Contact',
             "https://forum.generic-mapping-tools.org",
         ),
         (
             '<i class="fa fa-github fa-fw"></i> Source Code',
-            "https://github.com/GenericMappingTools/pygmt",
+            repository_url,
         ),
     ],
     # Custom variables to enable "Improve this page"" and "Download notebook"
@@ -164,8 +169,3 @@
     "github_version": "master",
     "commit": commit_link,
 }
-
-
-# Load the custom CSS files (needs sphinx >= 1.6 for this to work)
-def setup(app):
-    app.add_stylesheet("style.css")