String Input for Quote Now Respects Formatting (#130)

* Converted quote to the use of Raw blocks

* Cleaned up code comments

* Updated parameter language for consistency

* Added version history

* Added some install instructions

* Added doctests to usage docs

* Converted document doctests to include object return values

* Fixed up table doctest

docs/install.rst

@@ -3,6 +3,16 @@ Installation
 
 The quick and dirty way to install SnakeMD is to use pip:
 
-.. code-block::
+.. code-block:: shell
 
-    pip install SnakeMD
+    pip install snakemd
+
+If you'd like access to any pre-releases, you can also 
+install SnakeMD with the :code:`--pre` flag:
+
+.. code-block:: shell
+
+    pip install --pre snakemd
+
+Be aware that pre-releases are not suitable for production
+code.

docs/usage.rst

@@ -7,63 +7,71 @@ SnakeMD is a Python library for building markdown documents.
 We can use it by importing the SnakeMD module into our
 program directly:
 
-.. code-block:: python
+.. testcleanup:: usage
 
-    import snakemd
+    import os
+    os.remove("README.md")
+
+.. doctest:: usage
+
+    >>> import snakemd
 
 This way, we'll have access to all of the classes available
 in the SnakeMD module. From here, we can take advantage of
 a handy function to create a new document:
 
-.. code-block:: python 
+.. doctest:: usage
 
-    doc = snakemd.new_doc()
+    >>> doc = snakemd.new_doc()
 
 This will create a new :py:class:`snakemd.Document` object. Alternatively, we can 
 import the Document class directly:
 
-.. code-block:: python
+.. doctest:: usage
 
-    from snakemd import Document
+    >>> from snakemd import Document
 
 From here, we can instantiate the Document class:
 
-.. code-block:: python
+.. doctest:: usage
 
-    doc = Document()
+    >>> doc = Document()
 
 While there is nothing in our document currently, we can render
 an empty one as follows:
 
-.. code-block:: python
+.. doctest:: usage
 
-    doc.dump("README")
+    >>> doc.dump("README")
 
 This will create an empty README.md file in our working
 directory. Of course, if we want something more interesting,
 we'll have to add some content to our document. To start,
 we'll add a title to the document:
 
-.. code-block:: python 
+.. doctest:: usage
 
-    doc.add_heading("Why Use SnakeMD?")
+    >>> doc.add_heading("Why Use SnakeMD?") 
+    <snakemd.elements.Heading object at ...>
 
 From here, we can do pretty much anything we'd like. Some
 quick actions might be to include a paragraph about this 
 library as well as a list of reasons why we might use it:
 
-.. code-block:: python 
+.. doctest:: usage
 
-    p = doc.add_paragraph(
-      """
-      SnakeMD is a library for generating markdown, and here's
-      why you might choose to use it:
-      """
-    )
-    doc.add_unordered_list([
-        "SnakeMD makes it easy to create markdown files.",
-        "SnakeMD has been used to automate documentation for The Renegade Coder projects."
-    ])
+    >>> p = doc.add_paragraph(
+    ...     """
+    ...     SnakeMD is a library for generating markdown, and here's
+    ...     why you might choose to use it:
+    ...     """
+    ... )
+
+    >>> doc.add_unordered_list([
+    ...     "SnakeMD makes it easy to create markdown files.",
+    ...     "SnakeMD has been used to automate documentation for The Renegade Coder projects."
+    ... ]) 
+    <snakemd.elements.MDList object at ...>
 
 One thing that's really cool about using SnakeMD is that we can
 build out the structure of a document before we modify it to
@@ -74,21 +82,27 @@ that are generated as a result of their use. In this case, the
 method returns a Paragraph object which we can modify. Here's
 how we might insert a link to the docs:
 
-.. code-block:: python 
+.. doctest:: usage
 
-    p.insert_link("SnakeMD", "https://snakemd.therenegadecoder.com")
+    >>> p.insert_link("SnakeMD", "https://snakemd.therenegadecoder.com") 
+    <snakemd.elements.Paragraph object at ...>
 
 And if all goes well, we can output the results by outputting the
 document like before. Or, if we just need to see the results as
 a string, we can convert the document to a string directly:
 
-.. code-block:: python 
+.. doctest:: usage 
+
+    >>> print(doc) #doctest:+SKIP
+
+.. testcode:: usage 
+    :hide:
 
     print(doc)
 
 And this is what we'll get:
 
-.. code-block:: markdown
+.. testoutput:: usage
 
     # Why Use SnakeMD?
 
@@ -100,8 +114,7 @@ And this is what we'll get:
 For completion, here is a working program to generate the document
 from above in a file called README.md:
 
-.. code-block:: python
-    :linenos:
+.. testcode:: usage
 
     import snakemd
 

docs/version-history.rst

@@ -13,7 +13,13 @@ as follows:
 v2.x
 ----
 
-* v2.0.0b [:pr:`104`, :pr:`107`, :pr:`108`, :pr:`110`, :pr:`113`, :pr:`115`, :pr:`118`, :pr:`120`, :pr:`122`, :pr:`123`, :pr:`125`, :pr:`126`]
+* v2.0.0b2 [:pr:`129`, :pr:`130`]
+
+  * Converted all code snippets in docs to doctests
+  * Reworked string input for :code:`Quote` to pass directly through raw
+  * Updated language around parameters in documentation to provide a list of possible inputs and their effects
+
+* v2.0.0b1 [:pr:`104`, :pr:`107`, :pr:`108`, :pr:`110`, :pr:`113`, :pr:`115`, :pr:`118`, :pr:`120`, :pr:`122`, :pr:`123`, :pr:`125`, :pr:`126`]
 
   * Removed several deprecated items:
 

snakemd/document.py

@@ -55,7 +55,8 @@ def add_block(self, block: Block) -> Block:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_block(snakemd.Heading("Python is Cool!", 2)) 
+            >>> doc.add_block(snakemd.Heading("Python is Cool!", 2)) 
+            <snakemd.elements.Heading object at ...>
             >>> str(doc)
             '## Python is Cool!'
 
@@ -75,7 +76,8 @@ def add_raw(self, text: str) -> Raw:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_raw("X: 5\\nY: 4\\nZ: 3")
+            >>> doc.add_raw("X: 5\\nY: 4\\nZ: 3")
+            <snakemd.elements.Raw object at ...>
             >>> str(doc)
             'X: 5\\nY: 4\\nZ: 3'
 
@@ -96,7 +98,8 @@ def add_heading(self, text: str, level: int = 1) -> Heading:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_heading("Welcome to SnakeMD!")
+            >>> doc.add_heading("Welcome to SnakeMD!")
+            <snakemd.elements.Heading object at ...>
             >>> str(doc)
             '# Welcome to SnakeMD!'
 
@@ -123,7 +126,8 @@ def add_paragraph(self, text: str) -> Paragraph:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_paragraph("Mitochondria is the powerhouse of the cell.")
+            >>> doc.add_paragraph("Mitochondria is the powerhouse of the cell.")
+            <snakemd.elements.Paragraph object at ...>
             >>> str(doc)
             'Mitochondria is the powerhouse of the cell.'
 
@@ -144,7 +148,8 @@ def add_ordered_list(self, items: Iterable[str]) -> MDList:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_ordered_list(["Goku", "Piccolo", "Vegeta"])
+            >>> doc.add_ordered_list(["Goku", "Piccolo", "Vegeta"])
+            <snakemd.elements.MDList object at ...>
             >>> str(doc)
             '1. Goku\\n2. Piccolo\\n3. Vegeta'
 
@@ -165,7 +170,8 @@ def add_unordered_list(self, items: Iterable[str]) -> MDList:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_unordered_list(["Deku", "Bakugo", "Kirishima"])
+            >>> doc.add_unordered_list(["Deku", "Bakugo", "Kirishima"])
+            <snakemd.elements.MDList object at ...>
             >>> str(doc)
             '- Deku\\n- Bakugo\\n- Kirishima'
 
@@ -186,7 +192,8 @@ def add_checklist(self, items: Iterable[str]) -> MDList:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_checklist(["Okabe", "Mayuri", "Kurisu"])
+            >>> doc.add_checklist(["Okabe", "Mayuri", "Kurisu"])
+            <snakemd.elements.MDList object at ...>
             >>> str(doc)
             '- [ ] Okabe\\n- [ ] Mayuri\\n- [ ] Kurisu'
 
@@ -216,7 +223,8 @@ def add_table(
             >>> header = ["Place", "Name"]
             >>> rows = [["1st", "Robert"], ["2nd", "Rae"]]
             >>> align = [snakemd.Table.Align.CENTER, snakemd.Table.Align.RIGHT]
-            >>> _ = doc.add_table(header, rows, align=align)
+            >>> doc.add_table(header, rows, align=align)
+            <snakemd.elements.Table object at ...>
             >>> str(doc)
             '| Place | Name   |\\n| :---: | -----: |\\n| 1st   | Robert |\\n| 2nd   | Rae    |'
 
@@ -246,7 +254,8 @@ def add_code(self, code: str, lang: str = "generic") -> Code:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_code("x = 5")
+            >>> doc.add_code("x = 5")
+            <snakemd.elements.Code object at ...>
             >>> str(doc)
             '```generic\\nx = 5\\n```'
 
@@ -269,7 +278,8 @@ def add_quote(self, text: str) -> Quote:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_quote("Welcome to the Internet!")
+            >>> doc.add_quote("Welcome to the Internet!")
+            <snakemd.elements.Quote object at ...>
             >>> str(doc)
             '> Welcome to the Internet!'
 
@@ -290,7 +300,8 @@ def add_horizontal_rule(self) -> HorizontalRule:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_horizontal_rule()
+            >>> doc.add_horizontal_rule()
+            <snakemd.elements.HorizontalRule object at ...>
             >>> str(doc)
             '***'
 
@@ -313,9 +324,12 @@ def add_table_of_contents(self, levels: range = range(2, 3)) -> TableOfContents:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_table_of_contents()
-            >>> _ = doc.add_heading("First Item", 2)
-            >>> _ = doc.add_heading("Second Item", 2) 
+            >>> doc.add_table_of_contents()
+            <snakemd.templates.TableOfContents object at ...>
+            >>> doc.add_heading("First Item", 2)
+            <snakemd.elements.Heading object at ...>
+            >>> doc.add_heading("Second Item", 2) 
+            <snakemd.elements.Heading object at ...>
             >>> str(doc)
             '1. [First Item](#first-item)\\n2. [Second Item](#second-item)\\n\\n## First Item\\n\\n## Second Item'
 
@@ -339,7 +353,8 @@ def scramble(self) -> None:
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_horizontal_rule()
+            >>> doc.add_horizontal_rule()
+            <snakemd.elements.HorizontalRule object at ...>
             >>> doc.scramble()
             >>> str(doc)
             '***'
@@ -358,7 +373,8 @@ def dump(self, name: str, dir: str | os.PathLike = "", ext: str = "md", encoding
         .. doctest:: document
         
             >>> doc = snakemd.new_doc()
-            >>> _ = doc.add_horizontal_rule()
+            >>> doc.add_horizontal_rule()
+            <snakemd.elements.HorizontalRule object at ...>
             >>> doc.dump("README")
 
         :param str name: