From e9e89cfe21a6221f9966bee9a7c77548bf4b689e Mon Sep 17 00:00:00 2001
From: Alvin Wan <alvinwan@users.noreply.github.com>
Date: Mon, 3 Aug 2020 03:13:16 -0700
Subject: [PATCH] Version Bump + Docs (#110)

* fixes #106 version bump request

* finished basic guides (added modification)

* added crazy opt arg test from plastex/plastex#129
---
 TexSoup/__init__.py          |  2 +-
 docs/source/modification.rst | 94 +++++++++++++++++++++++++++++++++++-
 docs/source/soup.rst         | 14 ++++++
 setup.py                     |  2 +-
 tests/test_parser.py         |  6 +++
 5 files changed, 114 insertions(+), 4 deletions(-)

diff --git a/TexSoup/__init__.py b/TexSoup/__init__.py
index 7f0c064..db8dec6 100644
--- a/TexSoup/__init__.py
+++ b/TexSoup/__init__.py
@@ -7,7 +7,7 @@
 from TexSoup.tex import read
 from TexSoup.data import TexNode
 
-__version__ = '0.3.0'
+__version__ = '0.3.1'
 
 
 # noinspection PyPep8Naming
diff --git a/docs/source/modification.rst b/docs/source/modification.rst
index f7a5fe2..5ceef60 100644
--- a/docs/source/modification.rst
+++ b/docs/source/modification.rst
@@ -1,5 +1,95 @@
 Modification
 ===================================
 
-.. note:: This guide is coming soon. In the meantime, please see the package
-          reference for a :class:`TexSoup.data.TexNode`.
+You can also modify the document using the TexSoup tree, then export the changes
+back to a :math:`\LaTeX` file.
+
+Commands
+-----------------------------------
+
+As mentioned in :ref:`page-soup`, you can change commands and their arguments.
+
+    >>> soup = TexSoup(r'I am \textbf{\large Large and bold}')
+    >>> cmd = soup.textbf
+    >>> cmd.name = 'textit'
+    >>> cmd
+    \textit{\large Large and bold}
+
+You can set :code:`.string` for any single-argument command (e.g., :code:`\section`).
+
+    >>> cmd.string = 'corgis are the best'
+    >>> cmd
+    \textit{corgis are the best}
+
+You can do the same for any command in math mode.
+
+    >>> soup2 = TexSoup(r'$$\textrm{math}\sum$$')
+    >>> soup2.textrm.string = 'not math'
+    >>> soup2
+    $$\textrm{not math}\sum$$
+
+You can also remove any command in-place, by calling :code:`.delete` on it.
+
+    >>> soup2.textrm.delete()
+    >>> soup2
+    $$\sum$$
+
+Arguments
+-----------------------------------
+
+You can modify arguments just as you would a list.
+
+    >>> cmd.args.append('{moar}')
+    >>> cmd
+    \textit{corgis are the best}{moar}
+    >>> cmd.args.remove('{moar}')
+    >>> cmd
+    \textit{corgis are the best}
+    >>> cmd.args.extend(['[moar]', '{crazy}'])
+    \textit{corgis are the best}[moar]{crazy}
+    >>> cmd.args = cmd.args[:2]
+    >>> cmd
+    \textit{corgis are the best}[moar]
+
+Use the argument's :code:`.string` attribute to modify the argument's contents.
+
+    >>> cmd.args[0].string = 'no'
+    >>> cmd
+    \textit{no}[moar]
+
+Environments
+-----------------------------------
+
+Use the :code:`.string` attribute to modify any environment with only text content
+(i.e., a verbatim or math environment).
+
+    >>> soup = TexSoup(r'\begin{verbatim}Huehue\end{verbatim}')
+    >>> soup.verbatim.string = 'HUEHUE'
+    >>> soup
+    \begin{verbatim}HUEHUE\end{verbatim}
+    >>> soup = TexSoup(r'$$\text{math}$$')
+    >>> soup.text.string = ''
+
+You can add to an environment's contents using list-like operations, like
+:code:`.append`, :code:`.remove`, :code:`.insert`, and :code:`.extend`.
+
+    >>> from TexSoup import TexSoup
+    >>> soup = TexSoup(r'''
+    ... \begin{itemize}
+    ...     \item Hello
+    ...     \item Bye
+    ... \end{itemize}''')
+    >>> tmp = soup.item
+    >>> soup.itemize.remove(soup.item)
+    >>> soup.itemize
+    \begin{itemize}
+    \item Bye
+    \end{itemize}
+    >>> soup.insert(1, tmp)
+    >>> soup
+    \begin{itemize}
+    \item Hello
+    \item Bye
+    \end{itemize}
+
+See :class:`TexSoup.data.TexNode` for more utilities.
diff --git a/docs/source/soup.rst b/docs/source/soup.rst
index f259edc..49f2eaf 100644
--- a/docs/source/soup.rst
+++ b/docs/source/soup.rst
@@ -1,3 +1,5 @@
+.. _page-soup:
+
 Soup
 ===================================
 
@@ -23,8 +25,20 @@ You can also ask TexSoup to tolerate :math:`\LaTeX` errors. In which case,
 TexSoup will make a best-effort guess::
 
     >>> soup4 = TexSoup(r'\begin{itemize}\item hullo\end{enumerate}', tolerance=1)
+    >>> soup4
     \begin{itemize}\item hullo\end{itemize}\end{enumerate}
 
+To output the soup, you can call :code:`str()` on a :class:`TexSoup.data.TexNode` object, or any nested
+data structure.
+
+    >>> soup4
+    \begin{itemize}\item hullo\end{itemize}\end{enumerate}
+    >>> str(soup4)
+    '\\begin{itemize}\\item hullo\\end{itemize}\\end{enumerate}'
+    >>> soup4.item
+    \item hullo
+    >>> str(soup4.item)
+    '\\item hullo'
 
 Kinds of Objects
 ------------------------------------
diff --git a/setup.py b/setup.py
index f94a521..8b4f56f 100644
--- a/setup.py
+++ b/setup.py
@@ -31,7 +31,7 @@ def run_tests(self):
         sys.exit(errno)
 
 
-VERSION = '0.3.0'
+VERSION = '0.3.1'
 
 setup(
     name="TexSoup",
diff --git a/tests/test_parser.py b/tests/test_parser.py
index b1334eb..dfc0310 100644
--- a/tests/test_parser.py
+++ b/tests/test_parser.py
@@ -361,6 +361,12 @@ def test_def_item():
     assert soup.item is not None
 
 
+def test_grouping_optional_argument():
+    """Tests that grouping occurs correctly"""
+    soup = TexSoup(r"\begin{Theorem}[The argopt contains {$]\int_\infty$} the square bracket]\end{Theorem}")
+    assert len(soup.Theorem.args) == 1
+
+
 ##############
 # FORMATTING #
 ##############