Merge 071a9f4 into a39326f

pyinat · Jul 3, 2021 · 4477b9d · 4477b9d
2 parents a39326f + 071a9f4
commit 4477b9d
Show file tree

Hide file tree

Showing 17 changed files with 685 additions and 555 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ Contributions are welcome, and they are greatly appreciated! Every
 little bit helps, and credit will always be given.
 
 ## Installation
-To set up for local development (requires [poetry](python-poetry.org)):
+To set up for local development (requires [poetry](https://python-poetry.org)):
 ```bash
 $ git clone https://github.com/niconoe/pyinaturalist.git
 $ cd pyinaturalist
@@ -16,9 +16,11 @@ $ pre-commit install --config .github/pre-commit.yml
 ## Contribution Guidelines
 
 ### Documentation
-We use [Sphinx](http://www.sphinx-doc.org), and the references page is automatically
-generated thanks to `sphinx.ext.autodoc` and `sphinx_autodoc_typehints` extensions. All
-functions / methods / classes should have proper docstrings.
+For PRs, please include docstrings for all functions and classes.
+
+Project documentation is generated using [Sphinx](https://www.sphinx-doc.org),
+[MyST](https://myst-parser.readthedocs.io), and several Sphinx extensions and custom templates.
+See [conf.py][https://github.com/niconoe/pyinaturalist/blob/main/docs/conf.py] for more details.
 
 To build the docs locally:
 ```bash
@@ -44,8 +46,8 @@ This isn't needed for internal changes (tests, other docs, refactoring, etc.).
 We use the [pytest](https://docs.pytest.org/en/latest/) framework for unit testing.
 Just run the `pytest` command to run locally.
 
-We also use [tox](https://tox.readthedocs.io/en/latest/) to test multiple python versions.
-Use the `tox` command to run locally. This is also run by GitHub Actions on all pull requests.
+For PRs, GitHub Actions will also run tests for all supported python versions.
+You can use [tox](https://tox.readthedocs.io/en/latest/) to test these versions locally.
 
 ### Type Annotations
 All parameters and return values should have type annotations, which will be checked by `mypy` and

diff --git a/docs/conf.py b/docs/conf.py
@@ -27,35 +27,30 @@
 from os.path import abspath, basename, dirname, exists, join
 from shutil import copytree, rmtree
 
-
 # Avoid a potential circular import in nbsphinx
 try:
     import prompt_toolkit  # noqa
 except ImportError:
     pass
 
-DOCS_DIR = abspath(dirname(__file__))
+# Add project path so we can import our package
+sys.path.insert(0, '..')
+from pyinaturalist import __version__
+from pyinaturalist.constants import DOCS_DIR, PROJECT_DIR, EXAMPLES_DIR, SAMPLE_DATA_DIR
+from pyinaturalist.api_docs import document_models
+
+# Relevant doc directories used in extension settings
 CSS_DIR = join(DOCS_DIR, '_static')
-MODULE_DOCS_DIR = join(DOCS_DIR, 'modules')
-PROJECT_DIR = dirname(DOCS_DIR)
+MODULE_DOCS_DIR = 'modules'
 PACKAGE_DIR = join(PROJECT_DIR, 'pyinaturalist')
 
-# Source paths and symlink paths for static content to include
-DATA_DIR_SRC = join(PROJECT_DIR, 'test', 'sample_data')
+# Symlink paths for static content outside docs directory
 DATA_DIR_SYMLINK = join(DOCS_DIR, 'sample_data')
-IMAGE_DIR_SRC = join(DOCS_DIR, 'images')
-IMAGE_DIR_SYMLINK = join(DOCS_DIR, 'docs', 'images')
-NOTEBOOK_DIR_SRC = join(PROJECT_DIR, 'examples')
 NOTEBOOK_DIR_COPY = join(DOCS_DIR, 'examples')
 
-# Add project path so we can import our package
-sys.path.insert(0, PROJECT_DIR)
-from pyinaturalist import __version__
-from pyinaturalist.api_docs import document_models
-
 # General information about the project.
 copyright = '2021, Nicolas Noé, Jordan Cook'
-exclude_patterns = ['_build', 'modules/pyinaturalist.rst']
+exclude_patterns = ['_build', f'{MODULE_DOCS_DIR}/pyinaturalist.rst']
 html_static_path = ['_static']
 master_doc = 'index'
 needs_sphinx = '4.0'
@@ -64,7 +59,7 @@
 templates_path = ['_templates']
 version = release = __version__
 
-# Sphinx extension modules
+# Sphinx extensions
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
@@ -77,10 +72,21 @@
     'sphinx_copybutton',
     'sphinx_material',
     'sphinxcontrib.apidoc',
-    'm2r2',
+    'myst_parser',
     'nbsphinx',
 ]
 
+# MyST extensions
+myst_enable_extensions = [
+    "colon_fence",
+    # "deflist",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    # "substitution",
+]
+
 nbsphinx_allow_errors = True
 
 # Enable automatic links to other projects' Sphinx docs
@@ -115,7 +121,7 @@
 
 # apidoc settings
 apidoc_module_dir = PACKAGE_DIR
-apidoc_output_dir = 'modules'
+apidoc_output_dir = MODULE_DOCS_DIR
 apidoc_excluded_paths = ['api_docs/*', 'models/*', 'node_api.py', 'rest_api.py']
 apidoc_extra_args = ['--templatedir=_templates']
 apidoc_module_first = True
@@ -124,7 +130,7 @@
 
 # autosummary + automodapi settings
 automodapi_inheritance_diagram = False
-automodapi_toctreedirnm = 'modules'
+automodapi_toctreedirnm = MODULE_DOCS_DIR
 automodsumm_inherited_members = False
 autosummary_generate = True
 autosummary_generate_overwrite = True
@@ -181,11 +187,10 @@ def setup_external_files(app):
     """Create symlinks and copies of files outside docs directory so they can be accessed by Sphinx
     directives.
     """
-    make_symlink(IMAGE_DIR_SRC, IMAGE_DIR_SYMLINK)
-    make_symlink(DATA_DIR_SRC, DATA_DIR_SYMLINK)
+    make_symlink(SAMPLE_DATA_DIR, DATA_DIR_SYMLINK)
     # Unfortunately this can't be symlinked; nbsphinx will insert image links relative to this dir
     rmtree(NOTEBOOK_DIR_COPY, ignore_errors=True)
-    copytree(NOTEBOOK_DIR_SRC, NOTEBOOK_DIR_COPY)
+    copytree(EXAMPLES_DIR, NOTEBOOK_DIR_COPY)
 
 
 def make_symlink(src, dest):

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,4 @@
+(contributing)=
+
+```{include} ../CONTRIBUTING.md
+```
diff --git a/docs/contributing.rst b/docs/contributing.rst
diff --git a/docs/contributors.md b/docs/contributors.md
@@ -0,0 +1,2 @@
+```{include} ../CONTRIBUTORS.md
+```
diff --git a/docs/contributors.rst b/docs/contributors.rst
diff --git a/docs/history.md b/docs/history.md
@@ -0,0 +1,2 @@
+```{include} ../HISTORY.md
+```
diff --git a/docs/history.rst b/docs/history.rst
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,19 @@
+(index-page)=
+
+```{include} ../README.md
+:relative-docs: docs/
+:relative-images:
+```
+
+# Contents
+```{toctree}
+:maxdepth: 2
+
+user_guide
+examples
+endpoints
+reference
+contributing
+contributors
+history
+```
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/reference.md b/docs/reference.md
@@ -0,0 +1,37 @@
+(reference-docs)=
+
+# API Reference
+iNaturalist currently provides three API versions:
+
+- The original [Rails-based API](https://www.inaturalist.org/pages/api+reference) (v0)
+  that they also use internally: it is very complete and provides read/write access, but has less
+  consistent responses. It is likely that this API will be deprecated at some point in the future.
+- The [Node-based API](https://api.inaturalist.org/v1/docs/) (v1) allows read and write access
+  to most iNaturalist resources, and is generally faster and more consistent. It is
+  missing some of the features of the v0 API, however.
+- The [v2 API](https://api.inaturalist.org/v1/docs/) is currently in development, and will
+  eventually replace both the v0 and v1 APIs. see
+  [this forum thread](https://forum.inaturalist.org/t/obs-detail-on-api-v2-feedback/21215)
+  if you are interested in testing it out.
+
+Pyinaturalist provides functions to use the v0 and v1 APIs, with experimental v2 features coming soon.
+Also see {ref}`endpoints` for an overview of which iNaturalist endpoints are currently implemented.
+
+% Note: Source files for module docs are generated by sphinx-apidoc
+```{toctree}
+:caption: Main API Modules
+:titlesonly: true
+
+modules/pyinaturalist.v0
+modules/pyinaturalist.v1
+modules/pyinaturalist.v2
+pyinaturalist.models
+```
+
+```{toctree}
+:caption: Additional Utility Modules
+:glob: true
+:maxdepth: 1
+
+modules/pyinaturalist.[!vm]*
+```
diff --git a/docs/reference.rst b/docs/reference.rst