📚 New docs theme & Add comments

MANIFEST.in

@@ -3,7 +3,7 @@ recursive-include pop_tools *.yaml
 recursive-include pop_tools *.txt
 include pop_tools/input_templates/*
 include LICENSE
-include README.rst
+include README.md
 include requirements.txt
 
 recursive-exclude * __pycache__

README.md

@@ -0,0 +1,38 @@
+# POP-tools: Tools to support analysis of POP2-CESM model solutions with xarray
+
+| CI          | [![GitHub Workflow Status][github-ci-badge]][github-ci-link] [![GitHub Workflow Status][github-lint-badge]][github-lint-link] [![Code Coverage Status][codecov-badge]][codecov-link] |
+| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| **Docs**    |                                                                    [![Documentation Status][rtd-badge]][rtd-link]                                                                    |
+| **Package** |                                                         [![Conda][conda-badge]][conda-link] [![PyPI][pypi-badge]][pypi-link]                                                         |
+| **License** |                                                                        [![License][license-badge]][repo-link]                                                                        |
+
+## Installation
+
+pop-tools can be installed from PyPI with pip:
+
+```bash
+python -m pip install pop-tools
+```
+
+pop-tools is also available from conda-forge for conda installations:
+
+```bash
+conda install -c conda-forge pop-tools
+```
+
+See [documentation](https://pop-tools.readthedocs.io) for more information.
+
+[github-ci-badge]: https://img.shields.io/github/workflow/status/NCAR/pop-tools/CI?label=CI&logo=github&style=for-the-badge
+[github-lint-badge]: https://img.shields.io/github/workflow/status/NCAR/pop-tools/linting?label=linting&logo=github&style=for-the-badge
+[github-ci-link]: https://github.com/NCAR/pop-tools/actions?query=workflow%3ACI
+[github-lint-link]: https://github.com/NCAR/pop-tools/actions?query=workflow%3Alinting
+[codecov-badge]: https://img.shields.io/codecov/c/github/NCAR/pop-tools.svg?logo=codecov&style=for-the-badge
+[codecov-link]: https://codecov.io/gh/NCAR/pop-tools
+[rtd-badge]: https://img.shields.io/readthedocs/pop-tools/latest.svg?style=for-the-badge
+[rtd-link]: https://pop-tools.readthedocs.io/en/latest/?badge=latest
+[pypi-badge]: https://img.shields.io/pypi/v/pop-tools?logo=pypi&style=for-the-badge
+[pypi-link]: https://pypi.org/project/pop-tools
+[conda-badge]: https://img.shields.io/conda/vn/conda-forge/pop-tools?logo=anaconda&style=for-the-badge
+[conda-link]: https://anaconda.org/conda-forge/pop-tools
+[license-badge]: https://img.shields.io/github/license/NCAR/pop-tools?style=for-the-badge
+[repo-link]: https://github.com/NCAR/pop-tools

docs/_static/style.css

@@ -0,0 +1,15 @@
+/* Reduce left and right margins */
+
+.container,
+.container-lg,
+.container-md,
+.container-sm,
+.container-xl {
+  max-width: 1600px !important;
+}
+
+/* Make sidebar sticky */
+
+.bd-sidebar {
+  position: sticky !important;
+}

docs/environment.yml

@@ -0,0 +1,26 @@
+name: pop-tools-docs
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - dask
+  - fsspec
+  - jupyterlab
+  - matplotlib
+  - myst-nb
+  - netcdf4
+  - numba
+  - pip
+  - pooch
+  - python=3.8
+  - sphinx-book-theme >= 0.0.38
+  - sphinx-copybutton
+  - watermark
+  - xarray
+  - xgcm
+  - zarr
+  - pip:
+      - sphinxext-opengraph
+      - sphinx-comments
+      - -r ../requirements.txt
+      - -e ..

docs/source/conf.py

@@ -17,13 +17,13 @@
 # absolute, like shown here.
 #
 import datetime
+import inspect
 import os
 import sys
 
-import pop_tools
-
 sys.path.insert(0, os.path.abspath('../..'))
 
+import pop_tools
 
 # -- General configuration ---------------------------------------------
 
@@ -42,21 +42,32 @@
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'sphinx.ext.mathjax',  # for math equations
-    'nbsphinx',
     'sphinx.ext.napoleon',
+    'myst_nb',
+    'sphinx.ext.linkcode',
+    'sphinxext.opengraph',
+    'sphinx_copybutton',
+    'sphinx_comments',
 ]
 
-# Enable notebook execution
-# https://nbsphinx.readthedocs.io/en/0.4.2/never-execute.html
-nbsphinx_execute = 'auto'
-# Allow errors in all notebooks by
-nbsphinx_allow_errors = True
+# MyST config
+myst_enable_extensions = ['amsmath', 'colon_fence', 'deflist', 'html_image']
+myst_url_schemes = ('http', 'https', 'mailto')
 
-# Disable cell timeout
-nbsphinx_timeout = -1
+# sphinx-copybutton configurations
+copybutton_prompt_text = r'>>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
+copybutton_prompt_is_regexp = True
 
-nbsphinx_kernel_name = 'python3'
+# myst-nb configurations
+jupyter_execute_notebooks = 'auto'
 
+execution_timeout = 500
+
+
+comments_config = {
+    'utterances': {'repo': 'NCAR/pop-tools', 'optional': 'config', 'label': '💬 comment'},
+    'hypothesis': True,
+}
 
 extlinks = {
     'issue': ('https://github.com/NCAR/pop-tools/issues/%s', 'GH#'),
@@ -65,20 +76,33 @@
 
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
 autosummary_generate = []
+autodoc_typehints = 'none'
+
+# Napoleon configurations
 
-# Otherwise, the Return parameter list looks different from the Parameters list
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = False
 napoleon_use_rtype = False
+napoleon_preprocess_types = True
+
+# configuration for sphinxext.opengraph
+ogp_site_url = 'https://pop-tools.readthedocs.io/en/latest/'
+# ogp_image = ""
 
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
-html_static_path = ['../_build/html/_static']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.ipynb': 'myst-nb',
+    '.myst': 'myst-nb',
+}
+
 
 # The master toctree document.
 master_doc = 'index'
@@ -98,6 +122,7 @@
 # The full version, including alpha/beta/rc tags.
 release = pop_tools.__version__
 
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -123,7 +148,30 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_book_theme'
+html_title = ''
+
+html_context = {
+    'github_user': 'NCAR',
+    'github_repo': 'pop-tools',
+    'github_version': 'master',
+    'doc_path': 'docs',
+}
+html_theme_options = dict(
+    # analytics_id=''  this is configured in rtfd.io
+    # canonical_url="",
+    repository_url='https://github.com/NCAR/pop-tools',
+    repository_branch='master',
+    path_to_docs='docs',
+    use_edit_page_button=True,
+    use_repository_button=True,
+    use_issues_button=True,
+    home_page_in_toc=False,
+    extra_navbar='',
+    navbar_footer_text='',
+    extra_footer="""Theme by the <a href="https://ebp.jupyterbook.org">Executable Book Project</a>""",
+)
+
 html_logo = 'images/nsf.png'
 
 # Theme options are theme-specific and customize the look and feel of a
@@ -136,6 +184,13 @@
 # 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_css_files = ['style.css']
+
+
+today_fmt = '%Y-%m-%d'
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = today_fmt
 
 
 # -- Options for HTMLHelp output ---------------------------------------
@@ -205,3 +260,63 @@
     'xarray': ('http://xarray.pydata.org/en/stable/', None),
     'xgcm': ('https://xgcm.readthedocs.io/en/latest/', None),
 }
+
+
+# based on numpy doc/source/conf.py
+def linkcode_resolve(domain, info):
+    """
+    Determine the URL corresponding to Python object
+    """
+    if domain != 'py':
+        return None
+
+    modname = info['module']
+    fullname = info['fullname']
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split('.'):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError:
+            return None
+
+    try:
+        fn = inspect.getsourcefile(inspect.unwrap(obj))
+    except TypeError:
+        fn = None
+    if not fn:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except OSError:
+        lineno = None
+
+    if lineno:
+        linespec = f'#L{lineno}-L{lineno + len(source) - 1}'
+    else:
+        linespec = ''
+
+    fn = os.path.relpath(fn, start=os.path.dirname(pop_tools.__file__))
+
+    if '+' in pop_tools.__version__:
+        return f'https://github.com/NCAR/pop-tools/blob/master/pop_tools/{fn}{linespec}'
+    else:
+        return (
+            f'https://github.com/NCAR/pop-tools/blob/'
+            f'v{pop_tools.__version__}/pop_tools/{fn}{linespec}'
+        )
+
+
+def html_page_context(app, pagename, templatename, context, doctree):
+    # Disable edit button for docstring generated pages
+    if 'generated' in pagename:
+        context['theme_use_edit_page_button'] = False
+
+
+def setup(app):
+    app.connect('html-page-context', html_page_context)

docs/source/index.md

@@ -0,0 +1,26 @@
+```{include} ../../README.md
+
+```
+
+## Feedback
+
+If you encounter any errors or problems with **pop-tools**, please open an issue at the GitHub [main repository](http://github.com/NCAR/pop-tools/issues).
+
+## Documentation Contents
+
+```{toctree}
+---
+maxdepth: 2
+caption: User Guide
+---
+install.md
+examples
+```
+
+```{toctree}
+---
+maxdepth: 2
+caption: Reference
+---
+api.rst
+```