Incorporated More Precise Language Throughout Docs as Well as Doctests

.github/workflows/test.yml

@@ -1,4 +1,4 @@
-name: PyTest
+name: PyTest & Doctest
 
 on:
   pull_request:
@@ -24,9 +24,15 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
+        pip install -r docs/requirements.txt
 
     - name: PyTest
       run: coverage run --source=snakemd -m pytest
 
     - name: Coverage
       run: coverage report
+
+    - name: Doctest
+      run: |
+        cd docs
+        make doctest    

docs/conf.py

@@ -26,7 +26,12 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', "sphinx_issues", 'sphinx.ext.intersphinx']
+extensions = [
+    'sphinx.ext.autodoc', 
+    'sphinx_issues', 
+    'sphinx.ext.intersphinx', 
+    'sphinx.ext.doctest'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/docs/element-api.rst

@@ -17,6 +17,16 @@ is known as an element. Below is the element interface.
    :show-inheritance:
    :special-members: __str__
 
+For consistency, element mutators all return self to allow
+for method chaining. This is sometimes referred to as the
+fluent interface pattern, and it's particularly useful
+for applying a series of changes to a single element. This
+design choice most obviously shines in both :class:`snakemd.Paragraph`, 
+which allows different aspects of the text to be replaced
+over a series of chained methods, and :class:`snakemd.Inline`,
+which allows inline elements to be styled over a series of
+chained methods. 
+
 For practical purposes, elements cannot be constructed directly.
 Instead, they are broken down into two main categories:
 block and inline. 
@@ -31,11 +41,11 @@ custom blocks using the :func:`snakemd.Document.add_block` method. To make use
 of this method, blocks must be imported and constructed manually,
 like the following :class:`snakemd.Heading` example:
 
-.. code-block:: python 
+.. doctest:: block
 
-   from snakemd import Heading, new_doc
-   doc = new_doc()
-   doc.add_block(Heading("Hello, World!", 2))
+   >>> from snakemd import Heading, new_doc
+   >>> doc = new_doc()
+   >>> heading = doc.add_block(Heading("Hello, World!", 2))
 
 The remainder of this section introduces the Block interface
 as well as all of the Blocks currently available for use. 
@@ -135,11 +145,11 @@ the returned Heading object has no support for linking. However,
 with Inline elements, we can create a custom Heading to our
 standards:
 
-.. code-block:: python 
+.. doctest:: inline
 
-   from snakemd import Heading, Inline, new_doc
-   doc = new_doc()    
-   doc.add_block(Heading(Inline("Hello, World!", "https://snakemd.io"), 2))
+   >>> from snakemd import Heading, Inline, new_doc
+   >>> doc = new_doc()    
+   >>> heading = doc.add_block(Heading(Inline("Hello, World!", "https://snakemd.io"), 2))
 
 The remainder of this section introduces the Inline class.
 
@@ -150,3 +160,4 @@ Inline
    :members:
    :undoc-members:
    :show-inheritance:
+   :special-members: __str__

docs/resources.rst

@@ -9,11 +9,11 @@ date, with the most recently published resources first.
 v2.x
 ----
 
-- TBD
+* **2023-04-14**: `How to Migrate to SnakeMD 2.0.0 <https://therenegadecoder.com/code/how-to-migrate-to-snakemd-2-0-0/>`_
+* **2022-05-13**: `The Complete Guide to SnakeMD: A Python Library for Generating Markdown <https://therenegadecoder.com/code/the-complete-guide-to-snakemd-a-python-library-for-generating-markdown/>`_
 
 v0.x
 ----
 
-* **2022-05-13**: `The Complete Guide to SnakeMD: A Python Library for Generating Markdown <https://therenegadecoder.com/code/the-complete-guide-to-snakemd-a-python-library-for-generating-markdown/>`_
 * **2022-01-22**: `SnakeMD 0.10.x Features Checklists <https://therenegadecoder.com/meta/snakemd-0-10-x-features-checklists/>`_
-* **2021-09-24**: `How to Generate Markdown in Python Using SnakeMD <https://therenegadecoder.com/code/how-to-generate-markdown-in-python-using-snakemd/>`_
+* **2021-09-24**: `How to Generate Markdown in Python Using SnakeMD v0.x <https://therenegadecoder.com/code/how-to-generate-markdown-in-python-using-snakemd/>`_

setup.py

@@ -14,10 +14,11 @@
 MAJOR = 2
 MINOR = 0
 PATCH = 0
+PRE = "b2"
 
 name = "SnakeMD"
 version = f"{MAJOR}.{MINOR}"
-release = f"{MAJOR}.{MINOR}.{PATCH}b1"
+release = f"{MAJOR}.{MINOR}.{PATCH}{PRE}"
 setuptools.setup(
     name=name,
     version=release,

snakemd/__init__.py

@@ -9,10 +9,10 @@ def new_doc() -> Document:
     wants to take advantage of the procedural interface of SnakeMD.
     For those looking for a bit more control, each element class
     will need to be imported as needed.
-
-    .. code-block:: Python
-
-        doc = snakemd.new_doc()
+    
+    .. doctest:: document
+        
+        >>> doc = snakemd.new_doc()
 
     :return: 
         a new Document object