Skip to content

Commit 84e8d8a

Browse files
seismanseisman
committed
Merge branch 'main' into refactor/virtualfile_in
2 parents 2d55e5a + 0d31234 commit 84e8d8a

File tree

4 files changed

+234
-186
lines changed

4 files changed

+234
-186
lines changed

‎.github/workflows/ci_docs.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,13 @@ jobs:
147147
mv latex/pygmt.pdf pygmt-docs.pdf
148148
cd ../..
149149
150+
- name: Upload PDF as artifact for previewing on pull requests
151+
uses: actions/upload-artifact@v4.6.1
152+
if: github.event_name == 'pull_request' && matrix.os == 'ubuntu-latest'
153+
with:
154+
name: artifact-pygmt-docs-pdf
155+
path: doc/_build/pygmt-docs.pdf
156+
150157
- name: Copy the HTML ZIP archive and PDF to the html folder for dev version
151158
run: cp -v doc/_build/pygmt-docs.zip doc/_build/pygmt-docs.pdf doc/_build/html/
152159
if: github.event_name == 'push' && matrix.os == 'ubuntu-latest'

‎doc/conf.py

Lines changed: 94 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
"""
22
Sphinx documentation configuration file.
3+
4+
Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
35
"""
46

57
import datetime
@@ -10,7 +12,7 @@
1012
from pygmt.clib import required_gmt_version
1113
from pygmt.sphinx_gallery import PyGMTScraper
1214

13-
# Dictionary for dependency name and minimum required versions
15+
# Dictionary for dependency name and minimum required versions.
1416
requirements = {
1517
Requirement(requirement).name: str(Requirement(requirement).specifier)
1618
for requirement in importlib.metadata.requires("pygmt")
@@ -21,7 +23,28 @@
2123
"gmt": f">={required_gmt_version}",
2224
}
2325
)
26+
# Is a development version or not.
27+
isdev = "dev" in __version__ or __version__ == "unknown"
28+
# Some variables.
29+
repository = "GenericMappingTools/pygmt"
30+
repository_url = f"https://github.com/{repository}"
31+
doc_url = "https://pygmt.org/"
32+
if __commit__:
33+
commit_link = f'<a href="{repository_url}/commit/{__commit__}">{__commit__[:8]}</a>'
34+
else:
35+
commit_link = (
36+
f'<a href="{repository_url}/releases/tag/{__version__}">{__version__}</a>'
37+
)
2438

39+
# Projection information.
40+
project = "PyGMT"
41+
author = "The PyGMT Developers"
42+
copyright = f"2017-{datetime.date.today().year}, {author}" # noqa: A001
43+
version = "dev" if isdev else __version__
44+
release = __version__
45+
46+
# General configurations.
47+
needs_sphinx = "6.2"
2548
extensions = [
2649
"myst_nb",
2750
"sphinx.ext.autodoc",
@@ -39,48 +62,48 @@
3962
"sphinx_gallery.gen_gallery",
4063
"sphinxcontrib.cairosvgconverter",
4164
]
42-
43-
# Suppress warnings
65+
# Options for highlighting.
66+
pygments_style = "default"
67+
# Options for object signatures.
68+
add_function_parentheses = False
69+
# Options for source files.
70+
exclude_patterns = [
71+
"_build",
72+
"**.ipynb_checkpoints",
73+
# Workaround from https://github.com/executablebooks/MyST-NB/issues/363 to prevent
74+
# MyST-NB from parsing the .ipynb and .py files generated by Sphinx-Gallery.
75+
"intro/**.ipynb",
76+
"tutorials/**.ipynb",
77+
"gallery/**.ipynb",
78+
"projections/**.ipynb",
79+
"intro/**.py",
80+
"tutorials/**.py",
81+
"gallery/**.py",
82+
"projections/**.py",
83+
]
84+
# Options for source files.
85+
source_suffix = ".rst"
86+
source_encoding = "utf-8-sig"
87+
root_doc = "index"
88+
# Options for templating.
89+
templates_path = ["_templates"]
90+
# Options for warning control.
4491
suppress_warnings = [
4592
"myst.header", # Document headings start at H2, not H1
4693
]
4794

95+
# Options for autosummary.
4896
# Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
4997
autosummary_generate = []
5098

51-
# Auto-generate header anchors with MyST parser
52-
myst_heading_anchors = 4
53-
# MyST extensions
54-
# Reference: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
55-
myst_enable_extensions = [
56-
"attrs_inline", # Allow inline attributes after images
57-
"colon_fence", # Allow code fences using colons
58-
"substitution", # Allow substitutions
59-
]
60-
# These enable substitutions using {{ key }} in the Markdown files
61-
myst_substitutions = {
62-
"requires": requirements,
63-
}
64-
65-
# Configure MyST-NB
66-
# Reference: https://myst-nb.readthedocs.io/en/latest/configuration.html
67-
nb_render_markdown_format = "myst" # Format for text/markdown rendering
68-
69-
# Render the return argument and attribute lists in the same way as the parameter lists
70-
napoleon_use_rtype = False
71-
napoleon_use_ivar = True
72-
73-
# Configure sphinx_auto_typehints
74-
typehints_defaults = "comma"
75-
76-
# Define links to GMT docs
99+
# Options for extlinks.
77100
extlinks = {
78101
"gmt-docs": ("https://docs.generic-mapping-tools.org/6.5/%s", None),
79102
"gmt-term": ("https://docs.generic-mapping-tools.org/6.5/gmt.conf#term-%s", "%s"),
80103
"gmt-datasets": ("https://www.generic-mapping-tools.org/remote-datasets/%s", None),
81104
}
82105

83-
# Configure intersphinx
106+
# Options for intersphinx.
84107
intersphinx_mapping = {
85108
"contextily": ("https://contextily.readthedocs.io/en/stable/", None),
86109
"geopandas": ("https://geopandas.org/en/stable/", None),
@@ -94,13 +117,40 @@
94117
"xyzservices": ("https://xyzservices.readthedocs.io/en/stable", None),
95118
}
96119

97-
# Configure sphinx-copybutton
120+
# Options for napoleon.
121+
# Render the return argument and attribute lists in the same way as the parameter lists.
122+
napoleon_use_rtype = False
123+
napoleon_use_ivar = True
124+
125+
# Options for sphinx-copybutton.
98126
# Reference: https://sphinx-copybutton.readthedocs.io
99127
copybutton_prompt_text = r">>> |\.\.\. "
100128
copybutton_prompt_is_regexp = True
101129
copybutton_only_copy_prompt_lines = True
102130
copybutton_remove_prompts = True
103131

132+
# Options for MyST.
133+
myst_heading_anchors = 4 # Auto-generate header anchors with MyST parser
134+
# MyST extensions: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
135+
myst_enable_extensions = [
136+
"attrs_inline", # Allow inline attributes after images
137+
"colon_fence", # Allow code fences using colons
138+
"substitution", # Allow substitutions
139+
]
140+
# Enable substitutions using {{ key }} in the Markdown files
141+
myst_substitutions = {
142+
"requires": requirements,
143+
}
144+
145+
# Options for MyST-NB.
146+
# Reference: https://myst-nb.readthedocs.io/en/latest/configuration.html
147+
nb_render_markdown_format = "myst" # Format for text/markdown rendering
148+
149+
# Options for sphinx_auto_typehints.
150+
typehints_defaults = "comma"
151+
152+
# Options for Sphinx-Gallery.
153+
# Reference: https://sphinx-gallery.readthedocs.io/en/latest/configuration.html
104154
sphinx_gallery_conf = {
105155
# Set paths to your examples scripts
106156
"examples_dirs": [
@@ -151,68 +201,21 @@
151201
"nested_sections": False,
152202
}
153203

154-
# Configure Sphinx project
155-
templates_path = ["_templates"]
156-
exclude_patterns = [
157-
"_build",
158-
"**.ipynb_checkpoints",
159-
# Workaround from https://github.com/executablebooks/MyST-NB/issues/363 to prevent
160-
# MyST-NB from parsing the .ipynb and .py files generated by Sphinx-Gallery.
161-
"intro/**.ipynb",
162-
"tutorials/**.ipynb",
163-
"gallery/**.ipynb",
164-
"projections/**.ipynb",
165-
"intro/**.py",
166-
"tutorials/**.py",
167-
"gallery/**.py",
168-
"projections/**.py",
169-
]
170-
171-
source_suffix = ".rst"
172-
needs_sphinx = "6.2"
173-
# Encoding of source files
174-
source_encoding = "utf-8-sig"
175-
root_doc = "index"
176-
177-
# General information about the project
178-
year = datetime.date.today().year
179-
project = "PyGMT"
180-
copyright = f"2017-{year}, The PyGMT Developers" # noqa: A001
181-
if len(__version__.split("+")) > 1 or __version__ == "unknown":
182-
version = "dev"
183-
# Set base URL for dev version
184-
html_baseurl = "https://pygmt.org/dev/"
185-
else:
186-
version = __version__
187-
# Set base URL for stable version
188-
html_baseurl = "https://pygmt.org/latest/"
189-
release = __version__
190-
191-
html_last_updated_fmt = "%b %d, %Y"
192-
html_title = "PyGMT"
193-
html_short_title = "PyGMT"
204+
# Options for HTML output.
205+
html_theme = "sphinx_rtd_theme"
206+
html_theme_options = {}
207+
html_title = project
208+
html_short_title = project
209+
html_baseurl = f"{doc_url}/dev/" if isdev else f"{doc_url}/latest/"
194210
html_logo = ""
195211
html_favicon = "_static/favicon.png"
196-
html_static_path = ["_static"]
197212
html_css_files = ["style.css"]
213+
html_static_path = ["_static"]
198214
html_extra_path = []
199-
pygments_style = "default"
200-
add_function_parentheses = False
215+
html_last_updated_fmt = "%b %d, %Y"
201216
html_show_sourcelink = False
202-
html_show_sphinx = False
203217
html_show_copyright = True
204-
205-
# Configure theme
206-
html_theme = "sphinx_rtd_theme"
207-
html_theme_options = {}
208-
repository = "GenericMappingTools/pygmt"
209-
repository_url = "https://github.com/GenericMappingTools/pygmt"
210-
if __commit__:
211-
commit_link = f'<a href="{repository_url}/commit/{__commit__}">{__commit__[:8]}</a>'
212-
else:
213-
commit_link = (
214-
f'<a href="{repository_url}/releases/tag/{__version__}">{__version__}</a>'
215-
)
218+
html_show_sphinx = False
216219
html_context = {
217220
"menu_links": [
218221
(
@@ -247,5 +250,8 @@
247250
"commit": commit_link,
248251
}
249252

250-
# Configurations for LaTeX
253+
# Options for LaTeX output.
251254
latex_engine = "xelatex"
255+
latex_documents = [
256+
(root_doc, "pygmt.tex", "The PyGMT Documentation", author, "manual", True)
257+
]

‎doc/minversions.md

Lines changed: 32 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,13 @@ myst:
1212
title: "{{path}}"
1313
doc:
1414
url: "https://www.pygmt.org/{{path}}"
15-
title: "Docs"
15+
title: "Web"
16+
html:
17+
url: "https://github.com/GenericMappingTools/pygmt/releases/download/{{path}}/pygmt-docs.zip"
18+
title: "HTML+ZIP"
19+
pdf:
20+
url: "https://github.com/GenericMappingTools/pygmt/releases/download/{{path}}/pygmt-docs.pdf"
21+
title: "PDF"
1622
---
1723

1824
# Minimum Supported Versions
@@ -38,31 +44,31 @@ drop support for core (and optional) package dependencies earlier than recommend
3844
compatibility reasons.
3945
:::
4046

41-
| PyGMT Version | GMT | Python | NumPy | pandas | Xarray |
42-
|---|---|---|---|---|---|
43-
| [Dev][]* [<doc:dev>] | {{ requires.gmt }} | {{ requires.python }} | {{ requires.numpy }} | {{ requires.pandas }} | {{ requires.xarray }} |
44-
| <tag:v0.14.2> [<doc:v0.14.2>] | >=6.4.0 | >=3.11 | >=1.25 | >=2.0 | >=2023.04 |
45-
| <tag:v0.14.1> [<doc:v0.14.1>] | >=6.4.0 | >=3.11 | >=1.25 | >=2.0 | >=2023.04 |
46-
| <tag:v0.14.0> [<doc:v0.14.0>] | >=6.4.0 | >=3.11 | >=1.25 | >=2.0 | >=2023.04 |
47-
| <tag:v0.13.0> [<doc:v0.13.0>] | >=6.3.0 | >=3.10 | >=1.24 | >=1.5 | >=2022.09 |
48-
| <tag:v0.12.0> [<doc:v0.12.0>] | >=6.3.0 | >=3.10 | >=1.23 | >=1.5 | >=2022.06 |
49-
| <tag:v0.11.0> [<doc:v0.11.0>] | >=6.3.0 | >=3.9 | >=1.23 | | |
50-
| <tag:v0.10.0> [<doc:v0.10.0>] | >=6.3.0 | >=3.9 | >=1.22 | | |
51-
| <tag:v0.9.0> [<doc:v0.9.0>] | >=6.3.0 | >=3.8 | >=1.21 | | |
52-
| <tag:v0.8.0> [<doc:v0.8.0>] | >=6.3.0 | >=3.8 | >=1.20 | | |
53-
| <tag:v0.7.0> [<doc:v0.7.0>] | >=6.3.0 | >=3.8 | >=1.20 | | |
54-
| <tag:v0.6.1> [<doc:v0.6.1>] | >=6.3.0 | >=3.8 | >=1.19 | | |
55-
| <tag:v0.6.0> [<doc:v0.6.0>] | >=6.3.0 | >=3.8 | >=1.19 | | |
56-
| <tag:v0.5.0> [<doc:v0.5.0>] | >=6.2.0 | >=3.7 | >=1.18 | | |
57-
| <tag:v0.4.1> [<doc:v0.4.1>] | >=6.2.0 | >=3.7 | >=1.17 | | |
58-
| <tag:v0.4.0> [<doc:v0.4.0>] | >=6.2.0 | >=3.7 | >=1.17 | | |
59-
| <tag:v0.3.1> [<doc:v0.3.1>] | >=6.1.1 | >=3.7 | | | |
60-
| <tag:v0.3.0> [<doc:v0.3.0>] | >=6.1.1 | >=3.7 | | | |
61-
| <tag:v0.2.1> [<doc:v0.2.1>] | >=6.1.1 | >=3.6 | | | |
62-
| <tag:v0.2.0> [<doc:v0.2.0>] | >=6.1.1 | 3.6 - 3.8 | | | |
63-
| <tag:v0.1.2> [<doc:v0.1.2>] | >=6.0.0 | 3.6 - 3.8 | | | |
64-
| <tag:v0.1.1> [<doc:v0.1.1>] | >=6.0.0 | 3.6 - 3.8 | | | |
65-
| <tag:v0.1.0> [<doc:v0.1.0>] | >=6.0.0 | 3.6 - 3.8 | | | |
47+
| PyGMT Version | Documentation | GMT | Python | NumPy | pandas | Xarray |
48+
|---|---|---|---|---|---|---|
49+
| [Dev][]* | <doc:dev>, [HTML+ZIP](doc:dev/pygmt-docs.zip), [PDF](doc:dev/pygmt-docs.pdf) | {{ requires.gmt }} | {{ requires.python }} | {{ requires.numpy }} | {{ requires.pandas }} | {{ requires.xarray }} |
50+
| <tag:v0.14.2> | <doc:v0.14.2>, <html:v0.14.2> | >=6.4.0 | >=3.11 | >=1.25 | >=2.0 | >=2023.04 |
51+
| <tag:v0.14.1> | <doc:v0.14.1>, <html:v0.14.1> | >=6.4.0 | >=3.11 | >=1.25 | >=2.0 | >=2023.04 |
52+
| <tag:v0.14.0> | <doc:v0.14.0>, <html:v0.14.0> | >=6.4.0 | >=3.11 | >=1.25 | >=2.0 | >=2023.04 |
53+
| <tag:v0.13.0> | <doc:v0.13.0>, <html:v0.13.0> | >=6.3.0 | >=3.10 | >=1.24 | >=1.5 | >=2022.09 |
54+
| <tag:v0.12.0> | <doc:v0.12.0>, <html:v0.12.0> | >=6.3.0 | >=3.10 | >=1.23 | >=1.5 | >=2022.06 |
55+
| <tag:v0.11.0> | <doc:v0.11.0>, <html:v0.11.0> | >=6.3.0 | >=3.9 | >=1.23 | | |
56+
| <tag:v0.10.0> | <doc:v0.10.0>, <html:v0.10.0> | >=6.3.0 | >=3.9 | >=1.22 | | |
57+
| <tag:v0.9.0> | <doc:v0.9.0>, <html:v0.9.0> | >=6.3.0 | >=3.8 | >=1.21 | | |
58+
| <tag:v0.8.0> | <doc:v0.8.0>, <html:v0.8.0> | >=6.3.0 | >=3.8 | >=1.20 | | |
59+
| <tag:v0.7.0> | <doc:v0.7.0>, <html:v0.7.0> | >=6.3.0 | >=3.8 | >=1.20 | | |
60+
| <tag:v0.6.1> | <doc:v0.6.1>, <html:v0.6.1> | >=6.3.0 | >=3.8 | >=1.19 | | |
61+
| <tag:v0.6.0> | <doc:v0.6.0>, <html:v0.6.0> | >=6.3.0 | >=3.8 | >=1.19 | | |
62+
| <tag:v0.5.0> | <doc:v0.5.0>, <html:v0.5.0> | >=6.2.0 | >=3.7 | >=1.18 | | |
63+
| <tag:v0.4.1> | <doc:v0.4.1>, <html:v0.4.1> | >=6.2.0 | >=3.7 | >=1.17 | | |
64+
| <tag:v0.4.0> | <doc:v0.4.0>, <html:v0.4.0> | >=6.2.0 | >=3.7 | >=1.17 | | |
65+
| <tag:v0.3.1> | <doc:v0.3.1>, <html:v0.3.1> | >=6.1.1 | >=3.7 | | | |
66+
| <tag:v0.3.0> | <doc:v0.3.0>, <html:v0.3.0> | >=6.1.1 | >=3.7 | | | |
67+
| <tag:v0.2.1> | <doc:v0.2.1>, <html:v0.2.1> | >=6.1.1 | >=3.6 | | | |
68+
| <tag:v0.2.0> | <doc:v0.2.0>, <html:v0.2.0> | >=6.1.1 | 3.6 - 3.8 | | | |
69+
| <tag:v0.1.2> | <doc:v0.1.2>, <html:v0.1.2> | >=6.0.0 | 3.6 - 3.8 | | | |
70+
| <tag:v0.1.1> | <doc:v0.1.1>, <html:v0.1.1> | >=6.0.0 | 3.6 - 3.8 | | | |
71+
| <tag:v0.1.0> | <doc:v0.1.0>, <html:v0.1.0> | >=6.0.0 | 3.6 - 3.8 | | | |
6672

6773
*Dev reflects the main branch and is for the upcoming release.
6874

0 commit comments

Comments
 (0)