Update the option orders in the Sphinx configuration file (#3830)

Author: seisman

doc/conf.py

@@ -1,5 +1,7 @@
 """
 Sphinx documentation configuration file.
+
+Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 
 import datetime
@@ -10,7 +12,7 @@
 from pygmt.clib import required_gmt_version
 from pygmt.sphinx_gallery import PyGMTScraper
 
-# Dictionary for dependency name and minimum required versions
+# Dictionary for dependency name and minimum required versions.
 requirements = {
     Requirement(requirement).name: str(Requirement(requirement).specifier)
     for requirement in importlib.metadata.requires("pygmt")
@@ -21,7 +23,28 @@
         "gmt": f">={required_gmt_version}",
     }
 )
+# Is a development version or not.
+isdev = "dev" in __version__ or __version__ == "unknown"
+# Some variables.
+repository = "GenericMappingTools/pygmt"
+repository_url = f"https://github.com/{repository}"
+doc_url = "https://pygmt.org/"
+if __commit__:
+    commit_link = f'<a href="{repository_url}/commit/{__commit__}">{__commit__[:8]}</a>'
+else:
+    commit_link = (
+        f'<a href="{repository_url}/releases/tag/{__version__}">{__version__}</a>'
+    )
+
+# Projection information.
+project = "PyGMT"
+author = "The PyGMT Developers"
+copyright = f"2017-{datetime.date.today().year}, {author}"  # noqa: A001
+version = "dev" if isdev else __version__
+release = __version__
 
+# General configurations.
+needs_sphinx = "6.2"
 extensions = [
     "myst_nb",
     "sphinx.ext.autodoc",
@@ -39,48 +62,48 @@
     "sphinx_gallery.gen_gallery",
     "sphinxcontrib.cairosvgconverter",
 ]
-
-# Suppress warnings
+# Options for highlighting.
+pygments_style = "default"
+# Options for object signatures.
+add_function_parentheses = False
+# Options for source files.
+exclude_patterns = [
+    "_build",
+    "**.ipynb_checkpoints",
+    # Workaround from https://github.com/executablebooks/MyST-NB/issues/363 to prevent
+    # MyST-NB from parsing the .ipynb and .py files generated by Sphinx-Gallery.
+    "intro/**.ipynb",
+    "tutorials/**.ipynb",
+    "gallery/**.ipynb",
+    "projections/**.ipynb",
+    "intro/**.py",
+    "tutorials/**.py",
+    "gallery/**.py",
+    "projections/**.py",
+]
+# Options for source files.
+source_suffix = ".rst"
+source_encoding = "utf-8-sig"
+root_doc = "index"
+# Options for templating.
+templates_path = ["_templates"]
+# Options for warning control.
 suppress_warnings = [
     "myst.header",  # Document headings start at H2, not H1
 ]
 
+# Options for autosummary.
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
 autosummary_generate = []
 
-# Auto-generate header anchors with MyST parser
-myst_heading_anchors = 4
-# MyST extensions
-# Reference: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
-myst_enable_extensions = [
-    "attrs_inline",  # Allow inline attributes after images
-    "colon_fence",  # Allow code fences using colons
-    "substitution",  # Allow substitutions
-]
-# These enable substitutions using {{ key }} in the Markdown files
-myst_substitutions = {
-    "requires": requirements,
-}
-
-# Configure MyST-NB
-# Reference: https://myst-nb.readthedocs.io/en/latest/configuration.html
-nb_render_markdown_format = "myst"  # Format for text/markdown rendering
-
-# Render the return argument and attribute lists in the same way as the parameter lists
-napoleon_use_rtype = False
-napoleon_use_ivar = True
-
-# Configure sphinx_auto_typehints
-typehints_defaults = "comma"
-
-# Define links to GMT docs
+# Options for extlinks.
 extlinks = {
     "gmt-docs": ("https://docs.generic-mapping-tools.org/6.5/%s", None),
     "gmt-term": ("https://docs.generic-mapping-tools.org/6.5/gmt.conf#term-%s", "%s"),
     "gmt-datasets": ("https://www.generic-mapping-tools.org/remote-datasets/%s", None),
 }
 
-# Configure intersphinx
+# Options for intersphinx.
 intersphinx_mapping = {
     "contextily": ("https://contextily.readthedocs.io/en/stable/", None),
     "geopandas": ("https://geopandas.org/en/stable/", None),
@@ -94,13 +117,40 @@
     "xyzservices": ("https://xyzservices.readthedocs.io/en/stable", None),
 }
 
-# Configure sphinx-copybutton
+# Options for napoleon.
+# Render the return argument and attribute lists in the same way as the parameter lists.
+napoleon_use_rtype = False
+napoleon_use_ivar = True
+
+# Options for sphinx-copybutton.
 # Reference: https://sphinx-copybutton.readthedocs.io
 copybutton_prompt_text = r">>> |\.\.\. "
 copybutton_prompt_is_regexp = True
 copybutton_only_copy_prompt_lines = True
 copybutton_remove_prompts = True
 
+# Options for MyST.
+myst_heading_anchors = 4  # Auto-generate header anchors with MyST parser
+# MyST extensions: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+myst_enable_extensions = [
+    "attrs_inline",  # Allow inline attributes after images
+    "colon_fence",  # Allow code fences using colons
+    "substitution",  # Allow substitutions
+]
+# Enable substitutions using {{ key }} in the Markdown files
+myst_substitutions = {
+    "requires": requirements,
+}
+
+# Options for MyST-NB.
+# Reference: https://myst-nb.readthedocs.io/en/latest/configuration.html
+nb_render_markdown_format = "myst"  # Format for text/markdown rendering
+
+# Options for sphinx_auto_typehints.
+typehints_defaults = "comma"
+
+# Options for Sphinx-Gallery.
+# Reference: https://sphinx-gallery.readthedocs.io/en/latest/configuration.html
 sphinx_gallery_conf = {
     # Set paths to your examples scripts
     "examples_dirs": [
@@ -151,68 +201,21 @@
     "nested_sections": False,
 }
 
-# Configure Sphinx project
-templates_path = ["_templates"]
-exclude_patterns = [
-    "_build",
-    "**.ipynb_checkpoints",
-    # Workaround from https://github.com/executablebooks/MyST-NB/issues/363 to prevent
-    # MyST-NB from parsing the .ipynb and .py files generated by Sphinx-Gallery.
-    "intro/**.ipynb",
-    "tutorials/**.ipynb",
-    "gallery/**.ipynb",
-    "projections/**.ipynb",
-    "intro/**.py",
-    "tutorials/**.py",
-    "gallery/**.py",
-    "projections/**.py",
-]
-
-source_suffix = ".rst"
-needs_sphinx = "6.2"
-# Encoding of source files
-source_encoding = "utf-8-sig"
-root_doc = "index"
-
-# General information about the project
-year = datetime.date.today().year
-project = "PyGMT"
-copyright = f"2017-{year}, The PyGMT Developers"  # noqa: A001
-if len(__version__.split("+")) > 1 or __version__ == "unknown":
-    version = "dev"
-    # Set base URL for dev version
-    html_baseurl = "https://pygmt.org/dev/"
-else:
-    version = __version__
-    # Set base URL for stable version
-    html_baseurl = "https://pygmt.org/latest/"
-release = __version__
-
-html_last_updated_fmt = "%b %d, %Y"
-html_title = "PyGMT"
-html_short_title = "PyGMT"
+# Options for HTML output.
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {}
+html_title = project
+html_short_title = project
+html_baseurl = f"{doc_url}/dev/" if isdev else f"{doc_url}/latest/"
 html_logo = ""
 html_favicon = "_static/favicon.png"
-html_static_path = ["_static"]
 html_css_files = ["style.css"]
+html_static_path = ["_static"]
 html_extra_path = []
-pygments_style = "default"
-add_function_parentheses = False
+html_last_updated_fmt = "%b %d, %Y"
 html_show_sourcelink = False
-html_show_sphinx = False
 html_show_copyright = True
-
-# Configure theme
-html_theme = "sphinx_rtd_theme"
-html_theme_options = {}
-repository = "GenericMappingTools/pygmt"
-repository_url = "https://github.com/GenericMappingTools/pygmt"
-if __commit__:
-    commit_link = f'<a href="{repository_url}/commit/{__commit__}">{__commit__[:8]}</a>'
-else:
-    commit_link = (
-        f'<a href="{repository_url}/releases/tag/{__version__}">{__version__}</a>'
-    )
+html_show_sphinx = False
 html_context = {
     "menu_links": [
         (
@@ -247,5 +250,5 @@
     "commit": commit_link,
 }
 
-# Configurations for LaTeX
+# Options for LaTeX output.
 latex_engine = "xelatex"