From fc2d6441596e547ba8d8c9957b092724d8bb9ae3 Mon Sep 17 00:00:00 2001 From: jwansek Date: Thu, 28 Apr 2022 17:52:47 +0100 Subject: Started writing documentation --- docs/source/conf.py | 52 ++++++++++++++++++++++++++++++++++++++++++++++ docs/source/configfile.rst | 39 ++++++++++++++++++++++++++++++++++ docs/source/database.rst | 5 +++++ docs/source/docker.rst | 44 +++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 34 ++++++++++++++++++++++++++++++ docs/source/reflect.rst | 5 +++++ 6 files changed, 179 insertions(+) create mode 100644 docs/source/conf.py create mode 100644 docs/source/configfile.rst create mode 100644 docs/source/database.rst create mode 100644 docs/source/docker.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/reflect.rst (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..fd85d58 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,52 @@ +# 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(os.path.join("..", "..", "Smarker"))) +# print(os.listdir(os.path.abspath(os.path.join("..", "..", "Smarker")))) + + +# -- Project information ----------------------------------------------------- + +project = 'Smarker' +copyright = '2022, Eden Attenborough' +author = 'Eden Attenborough' + + +# -- 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.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon'] + +# 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 = [] + + +# -- 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 = 'alabaster' + +# 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'] \ No newline at end of file diff --git a/docs/source/configfile.rst b/docs/source/configfile.rst new file mode 100644 index 0000000..646230f --- /dev/null +++ b/docs/source/configfile.rst @@ -0,0 +1,39 @@ +.. _configfile: + +``smarker.conf``: Configuration File +==================================== + +Here is what it should look like. It needs to be in the same directory as the +source code. Its a standard .ini format. + +Once it's been created, you can safely forget about it since all of the options +can be over-ridden in command line arguments.:: + + [mysql] + host = vps.eda.gay + port = 3307 + user = root + passwd = ************ + + [tex] + columns = 1 + show_full_docs = True + show_source = True + show_all_regex_occurrences = True + show_all_run_output = True + + [md] + show_full_docs = False + show_source = False + show_all_regex_occurrences = True + show_all_run_output = False + + [txt] + show_full_docs = False + show_source = False + show_all_regex_occurrences = True + show_all_run_output = False + +The first block configures where your SQL server is. The other options are +the default options when generating reports. ``[tex]`` options are inherited +for rendering to PDF. \ No newline at end of file diff --git a/docs/source/database.rst b/docs/source/database.rst new file mode 100644 index 0000000..663c596 --- /dev/null +++ b/docs/source/database.rst @@ -0,0 +1,5 @@ +``database.py``: Interfacing with the database +============================================== + +.. automodule:: database + :members: \ No newline at end of file diff --git a/docs/source/docker.rst b/docs/source/docker.rst new file mode 100644 index 0000000..7c3237a --- /dev/null +++ b/docs/source/docker.rst @@ -0,0 +1,44 @@ +.. _docker: + +Running in docker +================= + +Running the system in docker has many advantages: + +* Don't have to worry about getting dependencies- the system requires many libraries to be avaliable on the PATH + +* Isolation: we are running remote code supplied by anyone, which can potentially be very dangerous. Docker isolates the dangerous code, a significant security concern + +* Makes the system be able to be used in Windows- Smarker has been tested in docker for windows using WSL for the backend + +Using docker +------------ + +We have a ``Dockerfile`` ready for use: ``sudo docker build -t smarker .`` + +To input files and get the output report we use docker volumes ``-v``. Unfortunately +docker seems to be rather buggy passing through single files, so we recommend making +a directory to pass through instead. + +Command line arguments can be replaced with environment variables, using the ``-e`` +flag in a ``key=value`` format. There is the additional environment variable ``SMARKERDEPS`` +which will pip install pypi modules at the start, deliminated with commas. + +.. code-block:: bash + + sudo docker run \ + -v "$(pwd)/../wsData.txt":/wsData.txt \ + -v "$(pwd)/100301654.zip":/tmp/100301654.zip \ + -v "$(pwd)/out/":/out/ \ + -e submission=/tmp/100301654.zip \ + -e assessment=example \ + -e SMARKERDEPS=matplotlib \ + -e format=pdf \ + -e output=/out/100301654.pdf \ + --rm smarker + +To list assessments in the database using docker: + +.. code-block:: bash + + sudo docker run -it --entrypoint python --rm smarker assessments.py --list yes \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..c238253 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,34 @@ +Welcome to Smarker's documentation! +=================================== + +Setting up +---------- + +* Set up a MySQL/MariaDB server. The database will be generated automatically. +* Add ``smarker.conf`` to the root directory of the code. See :ref:`configfile` for the structure of this file. +* Decide how you want to run the program: with or without docker. + +.. toctree:: + :maxdepth: 2 + :caption: Modules: + + reflect.rst + database.rst + +.. toctree:: + :maxdepth: 2 + :caption: Other Pages: + + configfile.rst + docker.rst + + + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/reflect.rst b/docs/source/reflect.rst new file mode 100644 index 0000000..c059206 --- /dev/null +++ b/docs/source/reflect.rst @@ -0,0 +1,5 @@ +``reflect.py``: Getting information about code +============================================== + +.. automodule:: reflect + :members: \ No newline at end of file -- cgit v1.2.3