doc: mtgjson documentation is ok, overhauled documentation in general

Guibod · Feb 17, 2023 · 9e5540a · 9e5540a
1 parent c4a6dff
commit 9e5540a
Show file tree

Hide file tree

Showing 17 changed files with 360 additions and 124 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,3 +8,5 @@ build
 .vscode
 **/__pycache__
 ._*
+/docs/source/_autosummary/
+/docs/source/reference/_autosummary/
diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst
diff --git a/docs/source/cli.rst b/docs/source/cli.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -32,26 +32,28 @@
 # ones.
 master_doc = "index"
 extensions = [
-    "sphinx.ext.autosummary",
     "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    # "sphinx.ext.napoleon",
     "sphinx_rtd_theme",
     "sphinxcontrib.autodoc_pydantic",
     "sphinx.ext.autosummary",
     "myst_parser",
 ]
 
+autosummary_generate = True
+autodoc_pydantic_model_members = True
+autodoc_pydantic_model_show_json = True
+autodoc_pydantic_settings_show_json = False
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-<<<<<<< HEAD
-exclude_patterns = []
-=======
 exclude_patterns = ["_build", "_templates"]
->>>>>>> 4144f04 (chore: linting alerts)
 
 
 # -- Options for HTML output -------------------------------------------------

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,7 +1,7 @@
 mightstone -  A toolbox for anything Magic The Gathering related
 ================================================================
 
-**Mightstone** is a package and a command line tool to interact with Magic The Gathering™️ resources online.
+**mightstone** is a package and a command line tool to interact with Magic The Gathering™️ resources online.
 
 Installation
 =============
@@ -17,8 +17,10 @@ Features
 ========
 
  * Mightstone use ``Pydantic`` and ``Asyncio`` as core feature.
- * Scryfall API
- * EDHREC (most features, the datamodel needs to be enhanced)
+ * Supported services:
+    * Scryfall API
+    * EDHREC (most features, the datamodel needs to be enhanced)
+    * MTGJSON
  * Magic The Gathering
     * A ColorPie generator
     * A robust Color identity Map
@@ -42,18 +44,19 @@ Plans
  * a finalized asyncio interface (I need to pick either aiostream or asyncstdlib)
  * I also hope to provide tools for pandas integration
 
-Getting started
-===============
+.. toctree::
+   :maxdepth: 1
+   :caption: Users
 
-For more information, check the :ref:`api-reference`.
+   users/installation
+   users/cli
 
 .. toctree::
-   :maxdepth: 2
-   :hidden:
+   :maxdepth: 1
+   :caption: Reference
 
-   cli
-   rule
-   api_reference
+   reference/api
+   reference/changelog
 
 
 Indices and tables

diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst
@@ -0,0 +1,55 @@
+.. _reference-index:
+
+API Reference
+=============
+
+EDHREC
+------
+
+Scryfall
+--------
+
+MTGJSON
+-------
+
+**MTGJSON** is an open-source project that catalogs all Magic: The Gathering data in portable formats. Using an aggregation process we fetch information between multiple resources and approved partners, and combine all that data in to various downloadable formats.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Feature
+     - Support
+   * - JSON data
+     - ✅
+   * - Compressed JSON data
+     - ✅ (except zip)
+   * - SQLite data
+     - ❌
+   * - CSV data
+     - ❌
+   * - GraphQL API
+     - ❌
+
+MtgJson Client
+~~~~~~~~~~~~~~
+
+.. autoclass:: mightstone.services.mtgjson.MtgJson
+   :members:
+
+Models
+~~~~~~
+
+.. currentmodule:: mightstone.services.mtgjson.models
+
+.. autosummary::
+   :toctree: _autosummary
+
+   Card
+   CardAtomicGroup
+   Set
+   SetList
+   Meta
+   Keywords
+   Deck
+   DeckList
+   CardTypes
diff --git a/docs/source/reference/changelog.rst b/docs/source/reference/changelog.rst
@@ -0,0 +1,2 @@
+.. include:: ../../../CHANGELOG.md
+   :parser: myst_parser.sphinx_
diff --git a/docs/source/rule.rst b/docs/source/rule.rst
diff --git a/docs/source/users/cli.rst b/docs/source/users/cli.rst
@@ -0,0 +1,23 @@
+.. _cli:
+
+Command Line Interface
+======================
+
+**mightstone** provide a command line interface built with :code:`Click`.
+
+.. code-block:: bash
+
+   python -m mightstone.cli --help
+
+
+Examples
+~~~~~~~~
+
+.. code-block:: bash
+
+   python -m mightstone.cli scryfall migration dd306737-d34c-4a0c-9e87-cd67bfa0d356
+
+
+.. code-block:: bash
+
+   python -m mightstone.cli scryfall collection id:683a5707-cddb-494d-9b41-51b4584ded69 "name:Ancient tomb" "set:dmu,collector_number:150"
diff --git a/docs/source/users/installation.rst b/docs/source/users/installation.rst
@@ -0,0 +1,40 @@
+============
+Installation
+============
+
+**mightstone** is a standalone python project that uses
+:code:`asyncio` and requires :code:`python >= 3.9.0`.
+
+Install
+=======
+
+**mightstone** needs to be installed just like any other python package
+into your documentation building environment:
+
+.. code-block:: bash
+
+   pip install mightstone
+
+or alternatively:
+
+.. code-block:: bash
+
+   poetry add mightstone
+
+
+Optional extensions
+===================
+
+Once installed, you'll need to enable it within sphinx' :code:`conf.py`:
+Mightstone use :code:`conf.py` https://github.com/ICRAR/ijson that relies on :code:`YAJL` https://lloyd.github.io/yajl/.
+IJson will use its python backend on the run if YAJL is not installed, but you cold benefit from installing YAJL locally.
+
+.. code-block:: bash
+
+   brew install yajl
+
+
+Configuration
+=============
+
+**mightstone** does not support configuration yet.