Prepared v0.14.0 Documentation (#95)

* Removed TODOs

* Fixed up all the references to element

* Replaced all the InlineText references

* Added the concept of a template to the docs

* Fixed docs

* Restructured docs

* Restructered API once again

* Separated code out into API files

* Fixed up docs

* Added version history

docs/docs.rst

@@ -4,139 +4,9 @@ Documentation
 The documentation page lists out all of the relevant classes
 and functions for generating markdown documents in Python.
 
-The SnakeMD Module
--------------------
+.. toctree::
+   :maxdepth: 2
 
-The SnakeMD module contains all of the functionality for
-generating markdown files with Python. To get started, 
-check out :ref:`usage_target` for information. Otherwise, 
-see the rest of this document for details on all the 
-functionality provided in snakemd. 
-
-.. automodule:: snakemd
-   :members:
-
-The SnakeMD Document
------------------------
-
-For the average user, the document object is the only
-object in the library necessary to create markdown files.
-Document objects are automatically created from the
-:func:`new_doc()` function of the SnakeMD module.
-
-.. autoclass:: snakemd.Document
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-The SnakeMD Elements
------------------------
-
-For users who want a little more control over how
-their markdown is formatted, SnakeMD provides, 
-a variety of markdown elements which you can create 
-and add to an existing document using the 
-:func:`add_element()` method. Elements all inherit 
-from the :class:`Element` "interface" which is defined 
-as follows:
-
-.. autoclass:: snakemd.Element
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Because of the increase in control granted to you
-by elements, there are opportunities where invalid
-markdown can be generated. In an attempt to provide
-a method of verifying the structure of the markdown,
-a :func:`verify()`` method has been provided for all 
-elements. The result of a call to :func:`verify`
-is a verification object which is defined as folows:
-
-.. autoclass:: snakemd.Verification
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-The remainder of this section outlines the various
-elements that can be added to a markdown document.
-
-CheckBox
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.CheckBox
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Header
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.Header
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Heading
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.Heading
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-HorizontalRule
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.HorizontalRule
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-InlineText
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.InlineText
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-MDCheckList
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.MDCheckList
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-MDList
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.MDList
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Paragraph
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.Paragraph
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Table
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.Table
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-TableOfContents
-^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: snakemd.TableOfContents
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   docs/document-api
+   docs/element-api
+   docs/template-api

docs/docs/document-api.rst

@@ -0,0 +1,44 @@
+The Document API 
+==========================
+
+SnakeMD is designed with different types of users in mind.
+The main type of user is the person who wants to design
+and generate markdown quickly without worrying too much
+about the format or styling of their documents. To help
+this type of user, we've developed a high-level API
+which consists of a single function, :func:`snakemd.new_doc()`.
+This function returns a Document object that is ready to be
+modified using any of the convenience methods available
+in the Document class. Both the :func:`snakemd.new_doc()` function 
+and the Document class are detailed below. 
+
+Module
+------
+
+The SnakeMD module contains all of the functionality for
+generating markdown files with Python. To get started, 
+check out :ref:`usage_target` for quickstart sample code. 
+
+.. automodule:: snakemd
+   :members:
+
+Document
+--------
+
+.. note:: 
+   All of the methods described in the Document class
+   are assumed to work without any :class:`snakemd.Element` imports.
+   In circumstances where methods may make use of
+   Elements, such as in :func:`add_table`, the snakemd
+   module will be referenced directly in the sample source 
+   code. 
+
+For the average user, the document object is the only
+object in the library necessary to create markdown files.
+Document objects are automatically created from the
+:func:`new_doc()` function of the SnakeMD module. 
+
+.. autoclass:: snakemd.Document
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/docs/element-api.rst

@@ -0,0 +1,142 @@
+The Element API
+=========================
+
+For users who want a little more control over how
+their markdown is formatted, SnakeMD provides a low-level
+API constructed from elements:
+
+.. autoclass:: snakemd.Element
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Elements are then broken down into two main types:
+block and inline. 
+
+Block Elements
+--------------
+
+SnakeMD block elements borrow from the idea of block-level elements
+from HTML. And because Markdown documents are constructed from a
+series of blocks, users of SnakeMD can seemlessly append their own
+custom blocks using the :func:`add_block` method. To make use
+of this method, blocks must be imported and constructed manually,
+like the following Heading example:
+
+.. code-block:: Python 
+
+    from snakemd import 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. 
+
+Block
+^^^^^
+
+All markdown blocks inherit from the Block interface. 
+
+.. autoclass:: snakemd.Block
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Verification
+^^^^^^^^^^^^
+
+.. warning::
+    The verification object and its implementation
+    throughout SnakeMD is in beta, and it should
+    not be used to verify production markdown. 
+
+Because of the increase in control granted to users
+by blocks, there are opportunities where invalid
+markdown can be generated. In an attempt to provide
+a method of verifying the structure of the markdown,
+a :func:`verify` method has been provided for all 
+elements. The result of a call to :func:`verify`
+is a verification object which is defined as folows:
+
+.. autoclass:: snakemd.Verification
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+The remainder of this page outlines the various
+elements that can be added to a markdown document.
+
+Heading
+^^^^^^^
+
+.. autoclass:: snakemd.Heading
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+HorizontalRule
+^^^^^^^^^^^^^^
+
+.. autoclass:: snakemd.HorizontalRule
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+MDList
+^^^^^^
+
+.. autoclass:: snakemd.MDList
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Paragraph
+^^^^^^^^^
+
+.. autoclass:: snakemd.Paragraph
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Raw
+^^^
+
+.. autoclass:: snakemd.Raw
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Table
+^^^^^
+
+.. autoclass:: snakemd.Table
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Inline Elements
+---------------
+
+One of the benefits of creating the Block elements directly
+over using the Document methods is the control users now have
+over the underlying structure and style. Now, instead of being
+bound to the string inputs, users can provide Inline elements
+directly. For example, maybe we want to be able to link a Heading.
+This is not exactly possible through the Document methods as even
+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 
+
+    from snakemd import Heading
+    doc.add_block(Heading(Inline("Hello, World!", "https://snakemd.io"), 2))
+
+The remainder of this section introduces the Inline class.
+
+Inline
+^^^^^^
+
+.. autoclass:: snakemd.Inline
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/docs/template-api.rst

@@ -0,0 +1,33 @@
+The Template API
+================
+
+While the document and element APIs are available
+for folks who are already somewhat familiar with Markdown, 
+a template system is slowly being developed for folks who
+are looking for a bit more convenience. Ultimately, these 
+folks can expect support for typical document sections such 
+as tables of contents, footers, and more. 
+
+Templates
+---------
+
+To allow for templates to be integrated with documents
+seamlessly, the Template interface was developed to
+inherit directly from the Element interface, just like
+Block and Inline. Therefore, templates can also be 
+verified. 
+
+.. autoclass:: snakemd.Template
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Below are a few existing templates. 
+
+TableOfContents
+---------------
+
+.. autoclass:: snakemd.TableOfContents
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/version-history.rst

@@ -10,6 +10,13 @@ In an effort to keep history of all the documentation
 for SnakeMD, we've included all old versions below
 as follows:
 
+* v0.14.0 [:pr:`84`, :pr:`86`, :pr:`89`, :pr:`90`, :pr:`91`]
+    * Added Raw block for user formatted text 
+    * Replaced InlineText with Inline
+    * Added Block and Inline classes 
+    * Deprecated MDCheckList and CheckBox
+    * Replaced render with bulit-in str method
+
 * v0.13.0 [:pr:`71`, :pr:`74`, :pr:`76`, :pr:`78`, :pr:`80`, :pr:`82`]
     * Created a replacement method for output_page called dump
     * Renamed Header class to Heading

snakemd/__init__.py

@@ -1,4 +1,4 @@
-from .generator import *
+from .document import *
 
 def new_doc(name: str = None) -> Document:
     """