Skip to content

Commit 757670d

Browse files
leouiedaleouieda
authored
Make the API reference manually (#209)
The automatically generated one is a bit difficult to follow and there is no separation between different types of functions/classes. The Figure and LibGMT methods are listed on the main page instead of only in the class pages. Each method has its own page, which will make it easier to include an example plot and when the library grows.
1 parent 98ca37c commit 757670d

File tree

6 files changed

+137
-53
lines changed

6 files changed

+137
-53
lines changed

‎doc/Makefile

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@ clean:
2525
rm -rf $(BUILDDIR)/doctrees
2626
rm -rf $(BUILDDIR)/linkcheck
2727
rm -rf modules
28-
rm -rf api/gmt*.rst
2928
rm -rf api/generated
3029
rm -rf .ipynb_checkpoints
3130
rm -rf tutorials/first-steps-*
@@ -42,7 +41,7 @@ api:
4241
@echo
4342
@echo "Building API docs."
4443
@echo
45-
$(SPHINXAUTOGEN) -i -t _templates -o api/ api/_generate_api.rst
44+
$(SPHINXAUTOGEN) -i -t _templates -o api/generated api/*.rst
4645

4746

4847
linkcheck:

‎doc/_templates/autosummary/class.rst

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,6 @@
44

55
.. autoclass:: {{ objname }}
66

7-
{% block methods_documentation %}
8-
{% if methods %}
9-
10-
.. raw:: html
11-
12-
<hr>
13-
14-
Methods Documentation
15-
---------------------
16-
17-
{% for item in methods %}
18-
{% if item != '__init__' %}
19-
.. automethod:: {{ objname }}.{{ item }}
20-
{% endif %}
21-
{% endfor %}
22-
23-
{% endif %}
24-
{% endblock %}
25-
267
.. raw:: html
278

289
<div style='clear:both'></div>
29-

‎doc/_templates/breadcrumbs.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
{% block breadcrumbs_aside %}
77
<li class="source-link">
88
{% if hasdoc(pagename) %}
9-
{% if pagename.startswith("api/") or suffix == ".ipynb" %}
9+
{% if pagename.startswith("api/generated") or suffix == ".ipynb" %}
1010
{% set title = "Suggested improvement for " + pagename %}
1111
{% set body = "Please describe what could be improved about this page or the typo/mistake that you found:" %}
1212
<a href="https://github.com/{{ github_repo }}/issues/new?title={{ title|urlencode }}&body={{ body|urlencode }}"

‎doc/api/_generate_api.rst

Lines changed: 0 additions & 17 deletions
This file was deleted.

‎doc/api/index.rst

Lines changed: 131 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,134 @@
33
API Reference
44
=============
55

6-
.. include:: gmt.rst
7-
.. include:: gmt.datasets.rst
8-
.. include:: gmt.exceptions.rst
9-
.. include:: gmt.clib.rst
10-
.. include:: gmt.helpers.rst
6+
.. currentmodule:: gmt
7+
8+
Plotting
9+
--------
10+
11+
All plotting is handled through the :class:`gmt.Figure` class and its methods.
12+
13+
.. autosummary::
14+
:toctree: generated
15+
16+
Figure
17+
18+
Plotting data and laying out the map:
19+
20+
.. autosummary::
21+
:toctree: generated
22+
23+
Figure.basemap
24+
Figure.coast
25+
Figure.plot
26+
Figure.grdimage
27+
Figure.logo
28+
29+
Saving and displaying the figure:
30+
31+
.. autosummary::
32+
:toctree: generated
33+
34+
Figure.savefig
35+
Figure.show
36+
Figure.psconvert
37+
38+
39+
Data Processing
40+
---------------
41+
42+
Operations on tabular data:
43+
44+
.. autosummary::
45+
:toctree: generated
46+
47+
info
48+
49+
Operations on grids:
50+
51+
.. autosummary::
52+
:toctree: generated
53+
54+
grdinfo
55+
56+
57+
Miscellaneous
58+
-------------
59+
60+
.. autosummary::
61+
:toctree: generated
62+
63+
which
64+
test
65+
print_libgmt_info
66+
67+
68+
Datasets
69+
--------
70+
71+
GMT/Python provides access to GMT's datasets through the :mod:`gmt.datasets` package.
72+
These functions will download the datasets automatically the first time they are used
73+
and store them in the GMT cache folder.
74+
75+
.. autosummary::
76+
:toctree: generated
77+
78+
datasets.load_earth_relief
79+
datasets.load_usgs_quakes
80+
datasets.load_japan_quakes
81+
82+
83+
Exceptions
84+
----------
85+
86+
All custom exceptions are derived from :class:`gmt.exceptions.GMTError`.
87+
88+
.. autosummary::
89+
:toctree: generated
90+
91+
exceptions.GMTError
92+
exceptions.GMTInvalidInput
93+
exceptions.GMTVersionError
94+
exceptions.GMTOSError
95+
exceptions.GMTCLibError
96+
exceptions.GMTCLibNoSessionError
97+
exceptions.GMTCLibNotFoundError
98+
99+
100+
GMT C API
101+
---------
102+
103+
The :mod:`gmt.clib` package is a wrapper for the GMT C API built using
104+
`ctypes <https://docs.python.org/3/library/ctypes.html>`__.
105+
Most calls to the C API happen through the :class:`gmt.clib.LibGMT` class.
106+
107+
.. autosummary::
108+
:toctree: generated
109+
110+
clib.LibGMT
111+
112+
Main methods (this is what the rest of the library uses):
113+
114+
.. autosummary::
115+
:toctree: generated
116+
117+
clib.LibGMT.call_module
118+
clib.LibGMT.grid_to_vfile
119+
clib.LibGMT.vectors_to_vfile
120+
clib.LibGMT.matrix_to_vfile
121+
clib.LibGMT.extract_region
122+
123+
Low level access (these are mostly used by the :mod:`gmt.clib` package):
124+
125+
.. autosummary::
126+
:toctree: generated
127+
128+
clib.LibGMT.create_session
129+
clib.LibGMT.destroy_session
130+
clib.LibGMT.get_constant
131+
clib.LibGMT.get_default
132+
clib.LibGMT.create_data
133+
clib.LibGMT.open_virtual_file
134+
clib.LibGMT.put_matrix
135+
clib.LibGMT.put_vector
136+
clib.LibGMT.write_data

‎gmt/__init__.py

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,10 @@
11
"""
22
The main API for GMT/Python.
33
4-
Functions and classes from ``gmt`` package offer access to GMT with input and
5-
output of Python data types.
6-
All plotting is handled through the :class:`gmt.Figure` class.
7-
8-
All of GMT/Python is operated on a "modern mode session" (new to GMT6). When
9-
you import the ``gmt`` library, a new session will be started automatically.
10-
The session will be closed when the current Python process terminates. Thus,
11-
the Python API does not expose the ``gmt begin`` and ``gmt end`` commands.
4+
All of GMT/Python is operated on a "modern mode session" (new to GMT6). When you import
5+
the ``gmt`` library, a new session will be started automatically. The session will be
6+
closed when the current Python process terminates. Thus, the Python API does not expose
7+
the ``gmt begin`` and ``gmt end`` commands.
128
"""
139
import atexit as _atexit
1410

0 commit comments

Comments
 (0)