diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..281d94a --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,39 @@ +name: Docs + +on: + push: + branches: + - main + - 39-read-the-docs + pull_request: + branches: + - main + workflow_dispatch: + +jobs: + sphinx: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + cache-dependency-path: doc/requirements.txt + + - name: Install Pandoc + run: | + sudo apt-get update + sudo apt-get install -y pandoc + + - name: Install documentation dependencies + run: | + python -m pip install --upgrade pip + python -m pip install -r doc/requirements.txt + + - name: Build documentation + run: | + python -m sphinx -W -b html doc/source doc/build/html diff --git a/.readthedocs.yaml b/.readthedocs.yaml index aa60a95..01c8bf4 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -5,9 +5,11 @@ version: 2 # Set the OS, Python version and other tools you might need build: - os: ubuntu-22.04 + os: ubuntu-24.04 tools: - python: "3.11" + python: "3.12" + apt_packages: + - pandoc # Build documentation in the "doc/" directory with Sphinx sphinx: @@ -22,10 +24,5 @@ formats: # Python requirements for building documentation python: install: - # Install the package itself - - method: pip - path: . - extra_requirements: - - docs # Install additional requirements for building docs - - requirements: doc/requirements.txt \ No newline at end of file + - requirements: doc/requirements.txt diff --git a/README.md b/README.md index 7936d6c..665e3d9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # PyFVCOM2 +[![Documentation Status](https://readthedocs.org/projects/pyfvcom2/badge/?version=latest)](https://pyfvcom2.readthedocs.io/en/latest/?badge=latest) + A Python package for processing FVCOM (Finite Volume Community Ocean Model) data. ## Description diff --git a/doc/requirements.txt b/doc/requirements.txt index 5e0f003..d911b4e 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -4,11 +4,12 @@ # Core Sphinx packages sphinx>=3.0 sphinx_rtd_theme>=0.5 +myst-parser # Sphinx extensions used in conf.py +sphinx-autodoc2 sphinx-copybutton nbsphinx -sphinxext-opengraph # Scientific documentation extensions numpydoc @@ -26,4 +27,4 @@ netcdf4>=1.5.0 xarray>=0.16.0 # For any plots or examples in documentation -matplotlib>=3.3.0 \ No newline at end of file +matplotlib>=3.3.0 diff --git a/doc/source/api.rst b/doc/source/api.rst index 3f57bac..ca1b207 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -1,12 +1,9 @@ .. _api: -API -=== - -For PyLag's API documentation, please refer to the following sections: +API Reference +============= .. toctree:: - :maxdepth: 1 - :caption: API Reference + :maxdepth: 4 - apidocs/index \ No newline at end of file + api/modules diff --git a/doc/source/api/modules.rst b/doc/source/api/modules.rst new file mode 100644 index 0000000..1acbc91 --- /dev/null +++ b/doc/source/api/modules.rst @@ -0,0 +1,7 @@ +API Reference +============= + +.. toctree:: + :maxdepth: 4 + + pyfvcom2 diff --git a/doc/source/api/pyfvcom2.bathy_smoother.rst b/doc/source/api/pyfvcom2.bathy_smoother.rst new file mode 100644 index 0000000..7fcab31 --- /dev/null +++ b/doc/source/api/pyfvcom2.bathy_smoother.rst @@ -0,0 +1,7 @@ +pyfvcom2.bathy\_smoother module +=============================== + +.. automodule:: pyfvcom2.bathy_smoother + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.cmems_reader.rst b/doc/source/api/pyfvcom2.cmems_reader.rst new file mode 100644 index 0000000..997bcd2 --- /dev/null +++ b/doc/source/api/pyfvcom2.cmems_reader.rst @@ -0,0 +1,7 @@ +pyfvcom2.cmems\_reader module +============================= + +.. automodule:: pyfvcom2.cmems_reader + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.coordinates.rst b/doc/source/api/pyfvcom2.coordinates.rst new file mode 100644 index 0000000..49b3abe --- /dev/null +++ b/doc/source/api/pyfvcom2.coordinates.rst @@ -0,0 +1,7 @@ +pyfvcom2.coordinates module +=========================== + +.. automodule:: pyfvcom2.coordinates + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.date_utils.rst b/doc/source/api/pyfvcom2.date_utils.rst new file mode 100644 index 0000000..23530c9 --- /dev/null +++ b/doc/source/api/pyfvcom2.date_utils.rst @@ -0,0 +1,7 @@ +pyfvcom2.date\_utils module +=========================== + +.. automodule:: pyfvcom2.date_utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.exceptions.rst b/doc/source/api/pyfvcom2.exceptions.rst new file mode 100644 index 0000000..6aef9c4 --- /dev/null +++ b/doc/source/api/pyfvcom2.exceptions.rst @@ -0,0 +1,7 @@ +pyfvcom2.exceptions module +========================== + +.. automodule:: pyfvcom2.exceptions + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.file_utils.rst b/doc/source/api/pyfvcom2.file_utils.rst new file mode 100644 index 0000000..597b271 --- /dev/null +++ b/doc/source/api/pyfvcom2.file_utils.rst @@ -0,0 +1,7 @@ +pyfvcom2.file\_utils module +=========================== + +.. automodule:: pyfvcom2.file_utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.fvcom_reader.rst b/doc/source/api/pyfvcom2.fvcom_reader.rst new file mode 100644 index 0000000..16046e2 --- /dev/null +++ b/doc/source/api/pyfvcom2.fvcom_reader.rst @@ -0,0 +1,7 @@ +pyfvcom2.fvcom\_reader module +============================= + +.. automodule:: pyfvcom2.fvcom_reader + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.fvcom_writer.rst b/doc/source/api/pyfvcom2.fvcom_writer.rst new file mode 100644 index 0000000..b0ef275 --- /dev/null +++ b/doc/source/api/pyfvcom2.fvcom_writer.rst @@ -0,0 +1,7 @@ +pyfvcom2.fvcom\_writer module +============================= + +.. automodule:: pyfvcom2.fvcom_writer + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.grid.rst b/doc/source/api/pyfvcom2.grid.rst new file mode 100644 index 0000000..107265e --- /dev/null +++ b/doc/source/api/pyfvcom2.grid.rst @@ -0,0 +1,7 @@ +pyfvcom2.grid module +==================== + +.. automodule:: pyfvcom2.grid + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.grid_builder.rst b/doc/source/api/pyfvcom2.grid_builder.rst new file mode 100644 index 0000000..17944af --- /dev/null +++ b/doc/source/api/pyfvcom2.grid_builder.rst @@ -0,0 +1,7 @@ +pyfvcom2.grid\_builder module +============================= + +.. automodule:: pyfvcom2.grid_builder + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.interpolation.rst b/doc/source/api/pyfvcom2.interpolation.rst new file mode 100644 index 0000000..2c054a4 --- /dev/null +++ b/doc/source/api/pyfvcom2.interpolation.rst @@ -0,0 +1,7 @@ +pyfvcom2.interpolation module +============================= + +.. automodule:: pyfvcom2.interpolation + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.interpolation_coordinates.rst b/doc/source/api/pyfvcom2.interpolation_coordinates.rst new file mode 100644 index 0000000..96cd029 --- /dev/null +++ b/doc/source/api/pyfvcom2.interpolation_coordinates.rst @@ -0,0 +1,7 @@ +pyfvcom2.interpolation\_coordinates module +========================================== + +.. automodule:: pyfvcom2.interpolation_coordinates + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.lanczos.rst b/doc/source/api/pyfvcom2.lanczos.rst new file mode 100644 index 0000000..d9a3d1b --- /dev/null +++ b/doc/source/api/pyfvcom2.lanczos.rst @@ -0,0 +1,7 @@ +pyfvcom2.lanczos module +======================= + +.. automodule:: pyfvcom2.lanczos + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.mesh_reader.rst b/doc/source/api/pyfvcom2.mesh_reader.rst new file mode 100644 index 0000000..c0ac1b8 --- /dev/null +++ b/doc/source/api/pyfvcom2.mesh_reader.rst @@ -0,0 +1,7 @@ +pyfvcom2.mesh\_reader module +============================ + +.. automodule:: pyfvcom2.mesh_reader + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.namelist.rst b/doc/source/api/pyfvcom2.namelist.rst new file mode 100644 index 0000000..513bb39 --- /dev/null +++ b/doc/source/api/pyfvcom2.namelist.rst @@ -0,0 +1,7 @@ +pyfvcom2.namelist module +======================== + +.. automodule:: pyfvcom2.namelist + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.nest.rst b/doc/source/api/pyfvcom2.nest.rst new file mode 100644 index 0000000..c446d6f --- /dev/null +++ b/doc/source/api/pyfvcom2.nest.rst @@ -0,0 +1,7 @@ +pyfvcom2.nest module +==================== + +.. automodule:: pyfvcom2.nest + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.obc.rst b/doc/source/api/pyfvcom2.obc.rst new file mode 100644 index 0000000..f308d22 --- /dev/null +++ b/doc/source/api/pyfvcom2.obc.rst @@ -0,0 +1,7 @@ +pyfvcom2.obc module +=================== + +.. automodule:: pyfvcom2.obc + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.ocean.rst b/doc/source/api/pyfvcom2.ocean.rst new file mode 100644 index 0000000..9eec786 --- /dev/null +++ b/doc/source/api/pyfvcom2.ocean.rst @@ -0,0 +1,7 @@ +pyfvcom2.ocean module +===================== + +.. automodule:: pyfvcom2.ocean + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.plotting.plot.rst b/doc/source/api/pyfvcom2.plotting.plot.rst new file mode 100644 index 0000000..026a3ba --- /dev/null +++ b/doc/source/api/pyfvcom2.plotting.plot.rst @@ -0,0 +1,7 @@ +pyfvcom2.plotting.plot module +============================= + +.. automodule:: pyfvcom2.plotting.plot + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.plotting.rst b/doc/source/api/pyfvcom2.plotting.rst new file mode 100644 index 0000000..088cd3a --- /dev/null +++ b/doc/source/api/pyfvcom2.plotting.rst @@ -0,0 +1,18 @@ +pyfvcom2.plotting package +========================= + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + pyfvcom2.plotting.plot + +Module contents +--------------- + +.. automodule:: pyfvcom2.plotting + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.restart.rst b/doc/source/api/pyfvcom2.restart.rst new file mode 100644 index 0000000..400bfd8 --- /dev/null +++ b/doc/source/api/pyfvcom2.restart.rst @@ -0,0 +1,7 @@ +pyfvcom2.restart module +======================= + +.. automodule:: pyfvcom2.restart + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.rst b/doc/source/api/pyfvcom2.rst new file mode 100644 index 0000000..4fe2fa2 --- /dev/null +++ b/doc/source/api/pyfvcom2.rst @@ -0,0 +1,49 @@ +pyfvcom2 package +================ + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + pyfvcom2.plotting + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + pyfvcom2.bathy_smoother + pyfvcom2.cmems_reader + pyfvcom2.coordinates + pyfvcom2.date_utils + pyfvcom2.exceptions + pyfvcom2.file_utils + pyfvcom2.fvcom_reader + pyfvcom2.fvcom_writer + pyfvcom2.grid + pyfvcom2.grid_builder + pyfvcom2.interpolation + pyfvcom2.interpolation_coordinates + pyfvcom2.lanczos + pyfvcom2.mesh_reader + pyfvcom2.namelist + pyfvcom2.nest + pyfvcom2.obc + pyfvcom2.ocean + pyfvcom2.restart + pyfvcom2.sigma + pyfvcom2.tide + pyfvcom2.tide_reader + pyfvcom2.weights_calculator + +Module contents +--------------- + +.. automodule:: pyfvcom2 + :members: + :show-inheritance: + :undoc-members: + :no-index: diff --git a/doc/source/api/pyfvcom2.sigma.rst b/doc/source/api/pyfvcom2.sigma.rst new file mode 100644 index 0000000..e3ed6dc --- /dev/null +++ b/doc/source/api/pyfvcom2.sigma.rst @@ -0,0 +1,7 @@ +pyfvcom2.sigma module +===================== + +.. automodule:: pyfvcom2.sigma + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.tide.rst b/doc/source/api/pyfvcom2.tide.rst new file mode 100644 index 0000000..ac153aa --- /dev/null +++ b/doc/source/api/pyfvcom2.tide.rst @@ -0,0 +1,7 @@ +pyfvcom2.tide module +==================== + +.. automodule:: pyfvcom2.tide + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.tide_reader.rst b/doc/source/api/pyfvcom2.tide_reader.rst new file mode 100644 index 0000000..05cd90f --- /dev/null +++ b/doc/source/api/pyfvcom2.tide_reader.rst @@ -0,0 +1,7 @@ +pyfvcom2.tide\_reader module +============================ + +.. automodule:: pyfvcom2.tide_reader + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/api/pyfvcom2.weights_calculator.rst b/doc/source/api/pyfvcom2.weights_calculator.rst new file mode 100644 index 0000000..c79e8a7 --- /dev/null +++ b/doc/source/api/pyfvcom2.weights_calculator.rst @@ -0,0 +1,7 @@ +pyfvcom2.weights\_calculator module +=================================== + +.. automodule:: pyfvcom2.weights_calculator + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/conf.py b/doc/source/conf.py index 5d574f1..d57d9f5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,9 +18,19 @@ # import os import sys +import types + +sys.path.insert(0, os.path.abspath('../..')) sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../../pyfvcom2')) +if 'pyfvcom2.version' not in sys.modules: + version_module = types.ModuleType('pyfvcom2.version') + version_module.short_version = 'X.Y.Z' + version_module.version = 'X.Y.Z' + version_module.full_version = 'X.Y.Z' + sys.modules['pyfvcom2.version'] = version_module + # -- General configuration ------------------------------------------------ @@ -32,9 +42,10 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ['autodoc2', + 'myst_parser', + 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', - 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', @@ -42,20 +53,17 @@ 'sphinx_copybutton', 'nbsphinx', 'sphinx_rtd_theme', - 'sphinxcontrib.googleanalytics', 'IPython.sphinxext.ipython_console_highlighting'] # Autodoc2 autodoc2_packages = ['../../pyfvcom2'] # Control autodoc2 output depth and content -autodoc2_output_dir = "apidocs" +autodoc2_output_dir = "../build/apidocs" autodoc2_index_template = None # Use default template # Configure autodoc2 to generate less nested content -autodoc2_module_all_regexes = [ - r"pyfvcom2\..*", -] +autodoc2_module_all_regexes = [] # Control autodoc2 content inclusion autodoc2_skip_module_regexes = [ @@ -66,6 +74,13 @@ # Autodoc napoleon_google_docstring = False napoleon_use_ivar = True +autodoc_mock_imports = [ + 'cartopy', + 'cmocean', + 'pyproj', + 'stripy', + 'utide', +] # Use this kernel instead of the one stored in the notebook metadata: nbsphinx_kernel_name = 'python3' @@ -76,10 +91,14 @@ # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -source_suffix = ['.rst', '.md'] +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} # The master toctree document. master_doc = 'index' +root_doc = 'index' # Control HTML table of contents depth html_theme_options = { @@ -120,7 +139,8 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['**.ipynb_checkpoints'] +exclude_patterns = ['**.ipynb_checkpoints', 'apidocs/**'] +suppress_warnings = ['myst.xref_missing', 'docutils'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -141,7 +161,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -212,9 +232,8 @@ 'Miscellaneous'), ] -# Execute notebooks -nbsphinx_execute = 'auto' -#nbsphinx_execute = 'always' +# Display the committed notebooks without executing them during RTD builds. +nbsphinx_execute = 'never' # Example configuration for intersphinx: refer to the Python standard library. diff --git a/doc/source/cookbook/index.rst b/doc/source/cookbook/index.rst index 5609e55..b89de28 100644 --- a/doc/source/cookbook/index.rst +++ b/doc/source/cookbook/index.rst @@ -8,8 +8,15 @@ In the cookbook, you can find hints and tips for working with PyFVCOM2. .. toctree:: :maxdepth: 1 - + + compare_tpxo_atlas_vs_coarse generate_fvcom_restart_using_cmems_data + tidal_harmonic_analysis_fvcom + interpolate_tpxo_tidal_harmonics + create_tide_only_inputs + interpolate_fvcom_data predict_tides_and_adjust_nest_forcing + generate_nest_forcing_file_from_cmems_data + tidal_harmonic_analysis_tide_gauge apply_ramp_demonstration - bathymetry_smoothing \ No newline at end of file + bathymetry_smoothing diff --git a/doc/source/index.rst b/doc/source/index.rst index f30f0b1..443c943 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,13 +1,9 @@ -PyFVCOM2 -======== - -PyFVCOM2 is a Python library designed to work with FVCOM model output data, providing tools for data analysis, visualization, and processing of unstructured grid ocean model results. It is intended to be the successor of PyFVCOM. - -Contents -======== +.. include:: ../../README.md + :parser: myst_parser.sphinx_ .. toctree:: :maxdepth: 1 + :caption: Contents installation cookbook/index @@ -15,4 +11,4 @@ Contents contributing license acknowledgements - + diff --git a/pyproject.toml b/pyproject.toml index 3200be7..e8e1b6b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -53,6 +53,11 @@ dev = [ docs = [ "sphinx>=3.0", "sphinx-rtd-theme>=0.5", + "myst-parser", + "sphinx-autodoc2", + "sphinx-copybutton", + "nbsphinx", + "numpydoc", "jupyter", "jupyter_client", "ipykernel",