Added bonus doc, Updated command line options doc

12 files changed, 103 insertions, 61 deletions

diff --git a/docs/README.rst b/docs/README.rst
index 86c571a..8c95bc7 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -13,8 +13,6 @@ minishell_test
 
 |pypi-python-version| |documentation-build| |travis-build|
 
-Test for 42 school's minishell project.
-
 .. image:: https://i.imgur.com/98xh2xY.gif
    :alt: preview
 
diff --git a/docs/bonus.rst b/docs/bonus.rst
index df4685e..f3d9a88 100644
--- a/docs/bonus.rst
+++ b/docs/bonus.rst
@@ -1,6 +1,26 @@
+.. program:: minishell_test
+
 Bonus
 =====
 
+See :ref:`how to enable the bonus tests in the configuration <config-bonus>`
+and the :option:`suite` option.
+
+Supported bonus:
+
+.. table::
+   :align: left
+   :widths: auto
+
+   ======  ====================
+   Name            Suite name
+   ======  ====================
+   ``&&``  ``flow/and``
+   ``||``  ``flow/or``
+   ``()``  ``flow/parenthesis``
+   ``*``   ``preprocess/glob``
+   ======  ====================
 
-See :ref:`config bonus`
-See :ref:`options bonus`
+.. note::
+   | If your bonus isn't supported, feel free to add them yourself and make a pull request.
+   | Take a look at :ref:`custom-tests` and :ref:`developers`.
diff --git a/docs/build-readme-md b/docs/build-readme-md
index 256bf63..c25a06b 100755
--- a/docs/build-readme-md
+++ b/docs/build-readme-md
@@ -1,4 +1,6 @@
 #!/bin/sh
 
+set -o xtrace
+
 # gfm = github flavored markdown
-pandoc README.rst -f rst -t gfm > ../README.md
+pandoc README.rst -f rst -t gfm | grep -v -e '^Note' -e '^Warning' > ../README.md
diff --git a/docs/conf.py b/docs/conf.py
index 339bb98..692a56c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -14,6 +14,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+from pathlib import Path
+
 # -- Project information -----------------------------------------------------
 
 project = 'minishell_test'
@@ -23,6 +25,7 @@ author = 'Charles Cabergs'
 # The full version, including alpha/beta/rc tags
 release = '1.0.1'
 
+# display_github = True
 
 # -- General configuration ---------------------------------------------------
 
@@ -31,6 +34,7 @@ release = '1.0.1'
 # ones.
 extensions = [
     "sphinx.ext.extlinks",
+    "sphinxcontrib.programoutput",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -41,7 +45,6 @@ templates_path = ['_templates']
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -49,6 +52,19 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 #
 html_theme = 'sphinx_rtd_theme'
 
+html_theme_options = {
+    "style_external_links": True,
+}
+
+github_url = 'https://github.com/cacharle/minishell_test'
+html_context = {
+    "display_github": True,
+    "github_user": "cacharle",
+    "github_repo": "minishell_test",
+    "conf_py_path": f"/{Path(__file__).parent.name}/",
+    "github_version": "master",
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
diff --git a/docs/config.rst b/docs/config.rst
index f35251d..c7995e3 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -22,18 +22,22 @@ Global
 
 Global settings are defined under the ``[minishell_test]`` section.
 
+.. _config-bonus:
 .. conf:: bonus
 
    :type: true|false
 
    Enable the bonus tests (:ref:`bonus`).
 
+
+.. _config-make:
 .. conf:: make
 
    :type: true|false
 
    Run the ``make`` command in your project directory before the test.
 
+.. _config-make-args:
 .. conf:: make_args
 
    :type: space separated list
@@ -41,7 +45,7 @@ Global settings are defined under the ``[minishell_test]`` section.
    | Argument given to the ``make`` command.
    | The default value (``MINISHELL_TEST_FLAGS=-DMINISHELL_TEST``) allows you to do conditional compilation
      to support both the ``-c`` option and the :ref:`subject`
-     (which doesn't say anything about options, so we assumed the minishell executable didn't take any).
+     (which doesn't say anything about options, so we assume the minishell executable didn't take any).
 
    | In your ``Makefile`` add ``$(MINISHELL_TEST_FLAGS)`` in your object compilation command.
      (e.g ``$(CC) $(CCFLAGS) -c -o $@ $<``)
@@ -64,6 +68,7 @@ Global settings are defined under the ``[minishell_test]`` section.
         }
         #endif
 
+.. _config-check-error-messages:
 .. conf:: check_error_messages
 
    :type: true|false
@@ -71,12 +76,13 @@ Global settings are defined under the ``[minishell_test]`` section.
    | If is ``true``, will ignore the content of the error messages outputted by the reference shell,
    | Useful if you have implemented your own error messages and don't want to copy bash's ones.
 
+.. _config-pager:
 .. conf:: pager
 
    :type: command name
 
    | Pager to use when viewing your results after the tests finished running.
-   | Will be called like so: ``{pager} {log_filename}``.
+   | Will be called like: ``{pager} {log_filename}``.
 
 Shell
 -----
@@ -93,6 +99,7 @@ Shell settings are defined under the ``[shell]`` section.
       Some of the default tests won't serve their purpose
       if the default available commands are not present.
 
+.. _config-path-variable:
 .. conf:: path_variable
 
    :type: string (``:`` separated directories)
@@ -108,11 +115,12 @@ Reference
 
 Reference shell settings are defined under the ``[shell:reference]`` section.
 
+.. _config-shell-reference-path:
 .. conf:: path
 
    :type: path
 
-   Path to reference shell, the one to which minishell will be compared.
+   Path to reference shell, to which your ``minishell`` will be compared.
 
    .. note::
       has to support the ``-c`` option, ``sh``, ``bash`` and ``zsh`` support it.
@@ -135,6 +143,7 @@ Timeout settings are defined under the ``[timeout]`` section.
 
    Time before a timeout occurs on a regular test.
 
+.. _config-timeout-leaks:
 .. conf:: leaks
 
    :type: float (seconds)
diff --git a/docs/custom_test.rst b/docs/custom_test.rst
index 1d5971c..fc5cf22 100644
--- a/docs/custom_test.rst
+++ b/docs/custom_test.rst
@@ -1,3 +1,5 @@
+.. _custom-tests:
+
 Add Custom Tests
 ================
 
diff --git a/docs/developers.rst b/docs/developers.rst
index 17307cd..024f100 100644
--- a/docs/developers.rst
+++ b/docs/developers.rst
@@ -1,3 +1,5 @@
+.. _developers:
+
 Developers
 ==========
 
diff --git a/docs/disclaimer.rst b/docs/disclaimer.rst
index 9e32b28..e523e8a 100644
--- a/docs/disclaimer.rst
+++ b/docs/disclaimer.rst
@@ -1,10 +1,13 @@
+.. program:: minishell_test
+
 Disclaimer
 ==========
 
 Environement variables
 ----------------------
 
-This test only gives the ``PATH`` and ``TERM`` environment variables to your minishell by default (see :ref:`config env`).
+| This test only gives the ``PATH`` and ``TERM`` environment variables to your minishell by default.
+| You can change the value of ``PATH`` in the :ref:`configuration <config-path-variable>`.
 
 You can test this quickly with :option:`--try`.
 
diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst
index e45ff38..15c1efc 100644
--- a/docs/gettingstarted.rst
+++ b/docs/gettingstarted.rst
@@ -12,12 +12,12 @@ Installation
 Compatibility
 +++++++++++++
 
-Your executable **must** support the ``-c`` option which allow to pass command as string.
+Your executable **must** support the ``-c`` option which allow to pass command as an argument.
 
 .. code-block::
 
     $ bash -c 'echo bonjour je suis | cat -e'
-    bonjour je suis$
+    bonjour he suis$
     $ ./minishell -c 'echo bonjour je suis | cat -e'
     bonjour je suis$
 
@@ -38,5 +38,5 @@ Run all the predefined tests:
 .. warning::
     If you get ``command not found``, do either of those things:
 
-    * ``~/.local/bin`` to your ``PATH`` environment variable.
-    * run ``$ python3 -m minishell_test`` instead of ``$ minishell_test``
+    * Add ``~/.local/bin`` to your ``PATH`` environment variable.
+    * Run ``$ python3 -m minishell_test`` instead of ``$ minishell_test``
diff --git a/docs/index.rst b/docs/index.rst
index ec08d8f..07ad2af 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,7 +1,5 @@
-.. program:: minishell_test
-
-minishell_test documentation
-============================
+Documentation of minishell_test
+===============================
 
 .. toctree::
    :maxdepth: 2
@@ -10,9 +8,8 @@ minishell_test documentation
    config
    options
    bonus
-   memory_leaks
-   linux
    custom_test
+   linux
    disclaimer
    developers
 
diff --git a/docs/memory_leaks.rst b/docs/memory_leaks.rst
deleted file mode 100644
index 27aca4c..0000000
--- a/docs/memory_leaks.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-
-Memory leaks
-------------
-
-See :ref:`options leaks`
diff --git a/docs/options.rst b/docs/options.rst
index 7c29529..7a294b5 100644
--- a/docs/options.rst
+++ b/docs/options.rst
@@ -1,71 +1,69 @@
 Command line Options
 ====================
 
-.. code-block:: txt
-
-    usage: minishell_test [-h] [-p PATH] [-l] [-t COMMAND] [-k] [-r BEGIN END]
-                          [--show-range] [-x] [-v] [-b] [-n] [-m] [-g]
-                          [suite ...]
+.. command-output:: minishell_test --help
+   :ellipsis: 3
 
 .. program:: minishell_test
 
 .. option:: suite
 
-   Test suites/group to run.
-   It tries to be smart and autocomplete the suite name
-   (e.g ./run int -> ./run preprocess/interpolation)
+   | Select the test suites/group to run.
+   | It tries to be smart and autocomplete the suite name,
+   | e.g ``$ minishell_test int`` -> ``$ minishell_test preprocess/interpolation``.
+   | See :option:`--list` to list the available suites.
 
+   .. command-output:: minishell_test -p ../../minishell inter
+      :ellipsis: 20
 
 .. option:: -h, --help
 
-   show this help message and exit
+   Print usage and exit.
 
 .. option:: -p <PATH>, --path <PATH>
 
-   Path to minishell directory
+   Path to the minishell directory, defaults to the current directory.
 
 .. option:: -l, --list
 
    Print available test suites
 
-.. option:: -t <COMMAND>, --try <COMMAND>
-
-   Run a custom command like this test would
-   (the only environment variable passed to your executable are TERM and PATH)
-
-.. option:: -k, --check-leaks
-
-   Run valgrind on tests (disable usual comparison with bash)
-
-.. option:: -r <BEGIN> <END>, --range <BEGIN> <END>
-
-    Range of test index to run (imply --show-index)
+   .. command-output:: minishell_test --list
+      :ellipsis: 15
 
-.. option:: --show-range
+.. option:: -t <COMMAND>, --try <COMMAND>
 
-   Show test index (useful with --range)
+   | Run a custom command like this test would
+   | (the only environment variable passed to your executable are TERM and PATH)
 
-.. option:: -x, --exit-first
+   .. command-output:: minishell_test -p ../../minishell --try 'echo bonjour | cat -e'
 
-    Exit on first fail
+.. option:: -g, --pager
 
-.. option:: -v, --verbose
+   After running the test, display the result in a pager of your choice, see :ref:`pager configuration <config-pager>`.
 
-    Increase verbosity level (e.g -vv == 2)
+Memory Leaks
+------------
 
-.. option:: -b, --bonus
+.. option:: -k, --check-leaks
 
-    Enable bonus tests
+   | Runs `valgrind <https://valgrind.org/>`_ on tests to check for memory leaks.
+   | (disable the usual comparison with the :ref:`reference shell <config-shell-reference-path>`)
 
-.. option:: -n, --no-bonus
+   .. warning::
+      | Running ``valgrind`` on each tests may take a while especially if your ``minishell`` isn't correctly optimized,
+      | See the :ref:`leaks timeout <config-timeout-leaks>` configuration variable to change the leak tests timeout.
 
-    Disable bonus tests
+.. option:: -r <BEGIN> <END>, --range <BEGIN> <END>
 
-.. option:: -m, --make
+   | Only run the test in the selected range,
+   | ``<BEGIN>`` and ``<END>`` must be test indices.
 
-    Make minishell and exit
+.. option:: --show-range
 
-.. option:: -g, --pager
+   | Show the tests indices.
+   | Both :option:`--check-leaks` and :option:`--range` imply this option.
 
-    After running the test, display the result in a pager of your choice
+.. option:: -x, --exit-first
 
+   Immediately stops when a test fails.