Merge pull request #107 from aburrell/readthedocs_hotfix

BUG: no fortran on readthedocs
aburrell · Dec 9, 2022 · 08c1a37 · 08c1a37
2 parents 063c5ad + 5ff7766
commit 08c1a37
Show file tree

Hide file tree

Showing 11 changed files with 80 additions and 78 deletions.
diff --git a/.gitignore b/.gitignore
@@ -52,6 +52,7 @@ docs/_build
 *~
 .*.sw[po]
 .build
+autoapi
 .ve
 .env
 .cache

diff --git a/docs/Makefile b/docs/Makefile
@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = src/apexpy
+SPHINXPROJ    = apexpy
 SOURCEDIR     = .
 BUILDDIR      = .build
 

diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,66 @@
+Reference
+=========
+
+The :py:class:`apexpy.Apex` class is used for all the main functionality
+(converting between coordinate systems, field line mapping, and calculating
+base vectors). The :py:mod:`apexpy.helpers` sub-module includes additional
+functions that may be useful, especially :py:func:`~apexpy.helpers.subsol`.
+The :py:mod:`apexpy.fortranapex` module is the interface to the apex Fortran
+library by Emmert et al. [2010] [1]_. The interface is not documented.
+Use :class:`apexpy.Apex` for all conversions and calculations. You can find
+some documentation of the actual Fortran library in the source file
+`apexsh.f90 <https://github.com/aburrell/apexpy/blob/main/fortranapex/apexsh.f90>`_.  These functions may also be accessed through the command-line interface.
+
+.. _api:
+
+API
+---
+
+.. toctree::
+   :maxdepth: 2
+
+   autoapi/generated/apexpy/index.rst
+
+
+.. _cli:
+
+Command-line interface
+----------------------
+
+.. highlight:: none
+
+When you install this package you will get a command called ``apexpy``, which
+is an interface to the :py:meth:`~apexpy.Apex.convert` method. See the
+documentation for this method for a more thorough explanation of arguments and
+behaviour.
+
+You can get help on the command by running ``apexpy -h``.
+
+.. code::
+
+    $ apexpy -h
+    usage: apexpy [-h] [--height HEIGHT] [--refh REFH] [-i FILE_IN]
+                  [-o FILE_OUT] SOURCE DEST DATE
+
+    Converts between geodetic, modified apex, quasi-dipole and MLT
+
+    positional arguments:
+      SOURCE                Convert from {geo, apex, qd, mlt}
+      DEST                  Convert to {geo, apex, qd, mlt}
+      DATE                  YYYY[MM[DD[HHMMSS]]] date/time for IGRF
+                            coefficients, time part required for MLT
+			    calculations
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --height HEIGHT       height for conversion
+      --refh REFH           reference height for modified apex coordinates
+      -i FILE_IN, --input FILE_IN
+                            input file (stdin if none specified)
+      -o FILE_OUT, --output FILE_OUT
+                            output file (stdout if none specified)
+
+.. [1] Emmert, J. T., A. D. Richmond, and D. P. Drob (2010),
+       A computationally compact representation of Magnetic-Apex
+       and Quasi-Dipole coordinates with smooth base vectors,
+       J. Geophys. Res., 115(A8), A08322, :doi:`10.1029/2010JA015326`.
diff --git a/docs/conf.py b/docs/conf.py
@@ -9,7 +9,8 @@
               'sphinx.ext.viewcode',
               'sphinx.ext.githubpages',
               'sphinx.ext.napoleon',
-              'sphinx.ext.extlinks']
+              'sphinx.ext.extlinks',
+              'autoapi.extension']
 
 # Define common elements
 
@@ -28,6 +29,13 @@
 match = re.findall(regex, text)
 version = release = match[0].strip("'")
 
+# Configure autoapi
+autoapi_type = 'python'
+autoapi_dirs = ['../apexpy']
+autoapi_keep_files = True
+autoapi_root = 'autoapi/generated'
+
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = 'sphinx_rtd_theme'
@@ -41,6 +49,7 @@
 html_sidebars = {'**': ['searchbox.html', 'globaltoc.html', 'sourcelink.html']}
 html_short_title = '-'.join([project, version])
 autodoc_member_order = 'bysource'
+autodoc_mock_imports = ['apexpy']
 napoleon_use_ivar = True
 napoleon_use_rtype = False
 napoleon_use_param = False

diff --git a/docs/index.rst b/docs/index.rst
@@ -8,7 +8,7 @@ Contents
    readme
    installation
    examples/index
-   reference/index
+   api
    contributing
    maintenance
    authors

diff --git a/docs/reference/Apex.rst b/docs/reference/Apex.rst
diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst
diff --git a/docs/reference/fortranapex.rst b/docs/reference/fortranapex.rst
diff --git a/docs/reference/helpers.rst b/docs/reference/helpers.rst
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,3 @@
 sphinx>=1.3
+sphinx-autoapi
 sphinx_rtd_theme
-.
-Original file line number
+Diff line change
@@ Expand Up / @@ -52,6 +52,7 @@ docs/_build @@
     *~
     .*.sw[po]
     .build
+    autoapi
     .ve
     .env
     .cache
@@ Expand Down @@