📚 Enable comments in docs via sphinx-comments

README.md

@@ -43,7 +43,7 @@ providing necessary functionality for searching, discovering, data access/loadin
 
   In [1]: import intake
 
-  In [2]: col_url = "https://raw.githubusercontent.com/NCAR/intake-esm-datastore/master/catalogs/pangeo-cmip6.json"
+  In [2]: col_url = "https://storage.googleapis.com/cmip6/pangeo-cmip6.json"
 
   In [3]: col = intake.open_esm_datastore(col_url)
 

ci/environment-upstream-dev.yml

@@ -1,6 +1,7 @@
 name: intake-esm-dev
 channels:
   - conda-forge
+  - nodefaults
 dependencies:
   - python=*=*cp*
   - boto3

ci/environment.yml

@@ -1,6 +1,7 @@
 name: intake-esm-dev
 channels:
   - conda-forge
+  - nodefaults
 dependencies:
   - python=*=*cp*
   - cftime

docs/environment.yml

@@ -1,11 +1,23 @@
 name: intake-esm-dev
 channels:
   - conda-forge
+  - nodefaults
 dependencies:
-  - intake-xarray
-  - nb_conda_kernels
-  - nbsphinx
-  - python=3.7
-  - sphinx_rtd_theme
-  - jupyter_client
+  - cftime
+  - jupyterlab
+  - matplotlib
+  - myst-nb
+  - pip
+  - python=3.8
+  - sphinx-book-theme >= 0.0.38
+  - sphinx-copybutton
+  - sqlalchemy==1.3.12
   - watermark
+  - zarr
+  - pip:
+      - gcsfs
+      - s3fs
+      - sphinxext-opengraph
+      - sphinx-comments
+      - -r ../requirements.txt
+      - -e ..

docs/source/catalogs.yaml

@@ -35,7 +35,7 @@ catalogs:
     dataset_docs_link: https://doi.org/10.5065/d6j101d1
 
   - name: CMIP6-GCP
-    url: https://raw.githubusercontent.com/NCAR/intake-esm-datastore/master/catalogs/pangeo-cmip6.json
+    url: https://storage.googleapis.com/cmip6/pangeo-cmip6.json
     description: CMIP6 Zarr data residing in Pangeo's Google Storage
     platform: Google Cloud Platform
     data_format: Zarr

docs/source/conf.py

@@ -1,16 +1,6 @@
 # -*- coding: utf-8 -*-
-#
-# complexity documentation build configuration file, created by
-# sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
 
+# import inspect
 import datetime
 import os
 import sys
@@ -43,28 +33,35 @@
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
+    # 'sphinx.ext.linkcode',
     'sphinx.ext.intersphinx',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'sphinx.ext.napoleon',
     'myst_nb',
+    'sphinxext.opengraph',
+    'sphinx_copybutton',
+    'sphinx_comments',
 ]
 
-autodoc_member_order = 'groupwise'
 
-myst_amsmath_enable = True
-myst_admonition_enable = True
-myst_html_img_enable = True
-myst_dmath_enable = True
-myst_deflist_enable = True
-myst_figure_enable = True
+# MyST config
+myst_enable_extensions = ['amsmath', 'colon_fence', 'deflist', 'html_image']
 myst_url_schemes = ('http', 'https', 'mailto')
-myst_heading_anchors = 2
-panels_add_boostrap_css = False
+
+# sphinx-copybutton configurations
+copybutton_prompt_text = r'>>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
+copybutton_prompt_is_regexp = True
+
+comments_config = {
+    'utterances': {'repo': 'NCAR/pop-tools', 'optional': 'config', 'label': '💬 comment'},
+    'hypothesis': False,
+}
+
 
 jupyter_execute_notebooks = 'cache'
 # jupyter_execute_notebooks = 'off'
-execution_timeout = 60
+execution_timeout = 600
 
 extlinks = {
     'issue': ('https://github.com/intake/intake-esm/issues/%s', 'GH#'),
@@ -75,9 +72,16 @@
 
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
 autosummary_generate = []
+autodoc_typehints = 'none'
+autodoc_member_order = 'groupwise'
+
+# 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
 
 
 # The suffix of source filenames.
@@ -116,23 +120,35 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'pydata_sphinx_theme'
+html_theme = 'sphinx_book_theme'
+html_title = ''
 
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = 'images/NSF_4-Color_bitmap_Logo.png'
+html_logo = '../_static/images/NSF_4-Color_bitmap_Logo.png'
 html_context = {
     'github_user': 'intake',
     'github_repo': 'intake-esm',
-    'github_version': 'master',
+    'github_version': 'main',
     'doc_path': 'docs',
 }
-html_theme_options = {
-    'github_url': 'https://github.com/intake/intake-esm',
-    'twitter_url': 'https://twitter.com/NCARXDev',
-    'show_toc_level': 1,
-}
+html_theme_options = dict(
+    # analytics_id=''  this is configured in rtfd.io
+    # canonical_url="",
+    repository_url='https://github.com/intake/intake-esm',
+    repository_branch='main',
+    path_to_docs='docs',
+    use_edit_page_button=True,
+    use_repository_button=True,
+    use_issues_button=True,
+    home_page_in_toc=False,
+    github_url='https://github.com/intake/intake-esm',
+    twitter_url='https://twitter.com/NCARXDev',
+    extra_navbar='',
+    navbar_footer_text='',
+    extra_footer="""Theme by the <a href="https://ebp.jupyterbook.org">Executable Book Project</a>""",
+)
 
 
 # The name of an image file (within the static path) to use as favicon of the
@@ -143,7 +159,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 = ['_build/html/_static']
+html_static_path = ['../_static']
 
 # Sometimes the savefig directory doesn't exist and needs to be created
 # https://github.com/ipython/ipython/issues/8733
@@ -212,6 +228,58 @@
 }
 
 
+# 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(intake_esm.__file__))
+
+#     if '+' in intake_esm.__version__:
+#         return f'https://github.com/intake/intake-esm/blob/master/intake_esm/{fn}{linespec}'
+#     else:
+#         return (
+#             f'https://github.com/intake/intake-esm/blob/'
+#             f'v{intake_esm.__version__}/intake_esm/{fn}{linespec}'
+#         )
+
+
 # https://www.ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/
 
 
@@ -227,9 +295,15 @@ def rstjinja(app, docname, source):
     source[0] = rendered
 
 
+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('source-read', rstjinja)
-    # app.add_stylesheet('style.css')
+    app.connect('html-page-context', html_page_context)
 
 
 with open('catalogs.yaml') as f:

docs/source/index.md

@@ -2,28 +2,31 @@
 
 ```
 
-## Feedback
+## Get in touch
 
-If you encounter any errors or problems with **intake-esm**, please open an issue at the GitHub [main repository](http://github.com/NCAR/intake-esm).
-
-## Documentation Contents
+- If you encounter any errors or problems with **pop-tools**, please open an issue at the GitHub [main repository](http://github.com/intake/intake-esm/issues).
+- If you have a question like “How do I find x?”, ask on [GitHub discussions](https://github.com/intake/intake-esm/discussions). Please include a self-contained reproducible example if possible.
 
 ```{toctree}
 ---
 maxdepth: 2
 caption: Using intake-esm
+hidden:
 ---
 installation.md
 user-guide/index.md
 supplemental-guide/index.md
+api.md
 ```
 
 ```{toctree}
 ---
 maxdepth: 2
-caption: Reference and contributing
+caption: Contribute to intake-esm
+hidden:
 ---
-api.md
 contributing.md
 changelog.md
+GitHub Repo <https://github.com/intake/intake-esm>
+GitHub discussions <https://github.com/intake/intake-esm/discussions>
 ```