Added docs draft

10 files changed, 379 insertions, 4 deletions

diff --git a/.gitignore b/.gitignore
index 3f00532..691b3c8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,5 +4,6 @@ bin/
 tags
 dist/
 *.egg-info
-build/
 .tox/
+build/
+docs/_build/
diff --git a/.travis.yml b/.travis.yml
index ae3fa12..2e93a07 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -18,12 +18,12 @@ addons:
       - valgrind
 
 # before_install:
-#   - [ "$TRAVIS_OS_NAME" = "osx" ] && brew update
-#   - [ "$TRAVIS_OS_NAME" = "osx" ] && brew install valgrind
+#   - if [ "$TRAVIS_OS_NAME" = "osx" ]; then brew update; fi
+#   - if [ "$TRAVIS_OS_NAME" = "osx" ]; then brew install valgrind; fi
 
 install:
   - pip install -e .
-  - pip install -r requirements.txt
+  - pip install -r requirements-dev.txt
   - git clone --recurse-submodule https://github.com/ouaisbrefbams/minishell /tmp/minishell
   - sed -i 's/-Werror//' /tmp/minishell/Makefile /tmp/minishell/libft/Makefile
 
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..cc274d9
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,88 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+from docutils import nodes
+from sphinx import addnodes
+
+# -- Project information -----------------------------------------------------
+
+project = 'minishell_test'
+copyright = '2021, Charles Cabergs'
+author = 'Charles Cabergs'
+
+# The full version, including alpha/beta/rc tags
+release = '1.0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# 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.extlinks",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# 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
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# 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".
+html_static_path = ['_static']
+
+def setup(app):
+    from sphinx.util.docfields import Field
+    app.add_object_type(
+        directivename="conf",
+        rolename="conf",
+        objname="configuration value",
+        indextemplate="pair: %s; configuration value",
+        doc_field_types=[
+            Field(
+                'type',
+                label='Type',
+                has_arg=False,
+                names=('type',),
+                bodyrolename='class'
+            ),
+            Field(
+                'default',
+                label='Default',
+                has_arg=False,
+                names=('default',),
+            ),
+        ]
+    )
+
+extlinks = {
+    "issue": ("https://github.com/cacharle/minishell_test/issues/%s", "#"),
+    "pull": ("https://github.com/cacharle/minishell_test/pull/%s", "p"),
+    "user": ("https://github.com/%s", "@"),
+}
diff --git a/docs/config.rst b/docs/config.rst
new file mode 100644
index 0000000..edd88d5
--- /dev/null
+++ b/docs/config.rst
@@ -0,0 +1,133 @@
+.. bt in -*- rst -*- mode!
+
+Configuration
+=============
+
+Configuration file
+------------------
+
+It looks for a ``minishell_test.cfg`` file in your project directory.
+
+Global
+------
+
+Global settings are defined under the ``minishell_test`` section:
+
+.. code-block:: cfg
+
+   [minishell_test]
+   bonus = true
+
+.. conf:: bonus
+
+   :type: true|false
+   :default: false
+
+    Run the bonus tests
+
+.. conf:: exec_name
+
+   :type: PATH
+   :default: minishell
+
+    Minishell executable name
+
+.. conf:: make
+
+   :type: true|false
+   :default: true
+
+    Run ``make`` in your project directory before the test
+
+.. conf:: pager
+
+   :type: NAME
+   :default: less
+
+    Pager to use when viewing your results
+
+.. conf:: log_path
+
+   :type: PATH
+   :default: minishell_test.log
+
+    File where to put the test results
+
+.. conf:: cache_path
+
+   :type: PATH
+   :default: $XDG_CACHE_HOME/minishell_test ^ ~/.cache/minishell_test
+
+
+Shell
+-----
+
+Shell settings are defined under the ``shell`` section:
+
+.. code-block:: cfg
+
+   [shell]
+   available_commands = ls,cat
+
+.. conf:: available_commands
+
+   :type: LIST
+   :default: rmdir env cat touch ls grep sh head
+
+    Commands available in test
+
+.. conf:: path_variable
+
+   :type: LIST
+   :default: {cache:executables_path}
+
+    ``$PATH`` environment variable passed to the shell
+
+Reference
++++++++++
+
+Reference shell settings are defined under the ``shell:reference`` section:
+
+.. code-block:: cfg
+
+   [shell:reference]
+   path = /bin/sh
+
+.. conf:: path
+
+   :type: PATH
+   :default: /bin/bash
+
+    Path to reference shell (shell which will be compared minishell)
+    has to support the ``-c`` option (``sh``, ``bash`` and ``zsh`` support it)
+
+.. conf:: args
+
+   :type: ARGV
+
+   Supplementary arguments to the reference shell
+   (e.g ``--posix`` can be used with bash for a more posix complient behavior)
+
+Timeout
+-------
+
+Timeout settings are defined under the ``timeout`` section:
+
+.. code-block:: cfg
+
+   [timeout]
+   leaks = 60
+
+.. conf:: test
+
+   :type: FLOAT
+   :default: 0.5
+
+   Time before a timeout occurs on a regular test (in seconds)
+
+.. conf:: leaks
+
+   :type: FLOAT
+   :default: 10
+
+   Time before a timeout occurs on a leak test (with valgrind) (in seconds)
diff --git a/docs/developers.rst b/docs/developers.rst
new file mode 100644
index 0000000..17307cd
--- /dev/null
+++ b/docs/developers.rst
@@ -0,0 +1,51 @@
+Developers
+==========
+
+Install requirements
+--------------------
+
+.. include:: ../requirements-dev.txt
+   :literal:
+
+.. code-block::
+
+    $ pip3 instal -r requirements-dev.txt
+
+Install in *editable* mode
+--------------------------
+
+.. code-block::
+
+    $ git clone https://github.com/cacharle/minishell_test
+    $ cd minishell_test
+    $ pip3 install -e .
+
+This make it possible to modify the source and see the changes live.
+
+Linting
+-------
+
+.. code-block::
+
+    $ flake8 minishell_test
+
+Type checking
+-------------
+
+.. code-block::
+
+    $ mypy minishell_test
+
+Unit Test
+---------
+
+.. code-block::
+
+    $ pytest
+
+Cross environment testing
+-------------------------
+
+.. code-block::
+
+    $ tox
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..109963f
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,94 @@
+minishell_test
+==============
+
+Test for 42 school's minishell project.
+
+.. .. image:: https://i.imgur.com/98xh2xY.gif
+
+Getting Started
+---------------
+
+Installation
+++++++++++++
+
+.. code-block::
+
+    $ pip3 install minishell-test
+    $ pip3 install --user minishell-test  # if you don't have root access
+
+Compatibility
++++++++++++++
+
+Your executable **must** support the ``-c`` option which allow to pass command as string.
+
+.. code-block::
+
+    $ bash -c 'echo bonjour je suis | cat -e'
+    bonjour je suis$
+    $ ./minishell -c 'echo bonjour je suis | cat -e'
+    bonjour je suis$
+
+
+.. note::
+    With this setup ``argv[2]`` is what you would usually get in ``line`` from ``get_next_line``.
+
+Usage
++++++
+
+Run all the predefined tests:
+
+.. code-block::
+
+    $ cd <MINISHELL>
+    $ minishell_test
+
+.. 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``
+
+
+Documentation
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
+   config
+   options
+   developers
+
+
+.. code-block::
+
+    $ minishell_test --help
+
+The options are explained in more details in :ref:`options <options>`.
+
+
+Environement variables
+----------------------
+
+This test only gives the ``PATH`` and ``TERM`` environment variables to your minishell by default (see :ref:`config env`).
+
+You can test this quickly with the `-t` option (See :ref:`options try`).
+
+.. warning::
+    Please check that your project still work with those settings before creating an issue or messaging me on.
+
+Bonus
+-----
+
+See :ref:`config bonus`
+See :ref:`options bonus`
+
+Memory leaks
+------------
+
+See :ref:`options leaks`
+
+Linux
+-----
+
+It will try to convert to output/status code of ``bash`` on Linux to the one on Mac.
diff --git a/docs/options.rst b/docs/options.rst
new file mode 100644
index 0000000..56a8c55
--- /dev/null
+++ b/docs/options.rst
@@ -0,0 +1,2 @@
+Command line Options
+====================
diff --git a/requirements.txt b/requirements-dev.txt
index bf40793..5e211a6 100644
--- a/requirements.txt
+++ b/requirements-dev.txt
@@ -1,4 +1,8 @@
+tox
 mypy==0.800
 flake8==3.8.4
 flake8_comprehensions==3.3.1
 pep8_naming==0.11.1
+pytest
+sphinx
+sphinx-rtd-theme
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..5e64fd1
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1 @@
+# do not remove, used by pytest
diff --git a/tox.ini b/tox.ini
index 8db5d81..10af4a5 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,5 +1,6 @@
 [tox]
 envlist = py36,py37,py38,py39
+distshare = {homedir}/.cache/tox/distshare
 
 [testenv]
 passenv =