Merge pull request #108 from gadomski/documentation-fixups

Documentation fixups
stac-utils · Sep 22, 2021 · 3d8803a · 3d8803a
2 parents d3db109 + 7b2679d
commit 3d8803a
Show file tree

Hide file tree

Showing 9 changed files with 19 additions and 15 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Fixed
+
+- Documentation lints [#108](https://github.com/stac-utils/pystac-client/pull/108)
+
 ## [0.3.0-beta.1] - 2021-09-22
 
 ### Added

diff --git a/README.md b/README.md
@@ -12,10 +12,10 @@ A Python client for working with [STAC](https://stacspec.org/) Catalogs and APIs
 
 ## Installation
 
-Install from PyPi. Other than PySTAC itself, the only dependency for pystac-client is the Python `requests` library.
+Install from PyPi. Other than [PySTAC](https://pystac.readthedocs.io) itself, the only dependencies for pystac-client is the Python [requests](https://docs.python-requests.org) and [dateutil](https://dateutil.readthedocs.io) libraries.
 
 ```shell
-pip install pystac-client
+$ pip install pystac-client
 ```
 
 ## Documentation
@@ -76,8 +76,9 @@ $ scripts/format
 $ git commit -a -m 'formatting updates'
 ```
 
-To build the documentation, use the `build-docs` script:
+To build the documentation, install the documentation requirements, then use the `build-docs` script:
 
 ```shell
+$ pip install -r requirements-docs.txt
 $ scripts/build-docs
 ```
diff --git a/docs/conf.py b/docs/conf.py
@@ -44,13 +44,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
- 'sphinx.ext.autodoc',
- 'sphinx.ext.viewcode',
- 'sphinx.ext.intersphinx',
- 'sphinx.ext.napoleon',
- 'sphinx.ext.extlinks',
- 'sphinxcontrib.fulltoc',
- 'nbsphinx'
+ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon',
+ 'sphinx.ext.extlinks', 'sphinxcontrib.fulltoc', 'nbsphinx', 'myst_parser'
 ]
 
 extlinks = {
@@ -70,7 +65,7 @@
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 source_suffix = [".rst", "*.md", "*.ipynb"]
-exclude_patterns = []
+exclude_patterns = ['build/*']
 
 
 # -- Options for HTML output -------------------------------------------------

diff --git a/docs/design/design_decisions.rst b/docs/design/design_decisions.rst
@@ -9,4 +9,4 @@ library. In general, this library makes an attempt to follow the design patterns
  :glob:
  :maxdepth: 1
 
- design/*.md
+ *
diff --git a/docs/index.rst b/docs/index.rst
@@ -53,3 +53,4 @@ Table of Contents
  api
  tutorials
  contributing
+ design/design_decisions
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -84,7 +84,8 @@ than once to use additional operators.
 
 ::
 
- stac-client search ${STAC_API_URL} -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 -q "eo:cloud_cover<10" "eo:cloud_cover>5" --matched
+ $ stac-client search ${STAC_API_URL} -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 -q "eo:cloud_cover<10" "eo:cloud_cover>5" --matched
+ 4 items matched
 
 Python
 ~~~~~~
@@ -123,4 +124,4 @@ Save all found items as a single FeatureCollection
 ::
 
  items = mysearch.get_all_items()
- items.save('items.json')
+ items.save_object('items.json')
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -1,7 +1,7 @@
 Usage
 #####
 
-PySTAC-Client (pystac-client) builds upon :ref:`~PySTAC<https://github.com/stac-utils/pystac>` library to add support
+PySTAC-Client (pystac-client) builds upon :ref:`~PySTAC<https://github.com/stac-utils/pystac>`_ library to add support
 for STAC APIs in addition to static STACs. PySTAC-Client can be used with static or dynamic (i.e., API)
 catalogs. Currently, pystac-client does not offer much in the way of additional functionality if using with
 static catalogs, as the additional features are for support STAC API endpoints such as `search`. However,

diff --git a/pystac_client/stac_api_io.py b/pystac_client/stac_api_io.py
@@ -143,6 +143,7 @@ def stac_object_from_dict(
  preserve_dict: bool = True,
  ) -> "STACObject_Type":
  """Deserializes a :class:`~pystac.STACObject` sub-class instance from a dictionary.
+
  Args:
  d : The dictionary to deserialize
  href : Optional href to associate with the STAC object

diff --git a/requirements-docs.txt b/requirements-docs.txt
@@ -2,5 +2,6 @@ ipykernel~=6.2
 ipython~=7.27
 Sphinx~=4.1
 sphinxcontrib-fulltoc~=1.2
+myst-parser~=0.15.2
 nbsphinx~=0.8
 jinja2<4.0