diff --git a/.gitignore b/.gitignore index c531d98..c624ebd 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ +.DS_Store *.elc +docs/_build/ diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..08d4699 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,25 @@ +language: python +notifications: + email: false + +branches: + only: + - master + +cache: + pip: true + apt: true + +matrix: + include: + - python: "3.7-dev" # 3.7 development branch + +install: + - pip install -r docs_requirements.txt + +script: + - ( cd docs; make html ) + - travis-sphinx build --source=docs/ + +after_success: + - travis-sphinx deploy -c docs-fs.codegra.de diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..6e8bf73 --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.1.0 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..74a5269 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = -W +SPHINXBUILD = python3 -msphinx +SPHINXPROJ = CodeGradefs +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/_images/favicon.ico b/docs/_static/_images/favicon.ico new file mode 100644 index 0000000..1a69c24 Binary files /dev/null and b/docs/_static/_images/favicon.ico differ diff --git a/docs/_static/_images/logo.svg b/docs/_static/_images/logo.svg new file mode 100644 index 0000000..6b40184 --- /dev/null +++ b/docs/_static/_images/logo.svg @@ -0,0 +1,18 @@ + + + CodeGra.de + + + + + diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 0000000..895cab8 --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,33 @@ +.wy-nav-content { + width: 60em; /* Change as you like. */ + max-width: 100% !important; +} + +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} + +.rst-content kbd { + display: inline-block; + padding: 3px 5px; + font-size: 11px; + line-height: 10px; + color: #444d56; + vertical-align: middle; + background-color: #fafbfc; + border: solid 1px #c6cbd1; + border-bottom-color: rgb(198, 203, 209); + border-bottom-color: #959da5; + border-radius: 3px; + box-shadow: inset 0 -1px 0 #959da5; +} diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 0000000..3e44f4a --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,4 @@ +{% extends "!layout.html" %} +{% block extrahead %} + +{% endblock %} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..93ce4a7 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,179 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# CodeGra.de documentation build configuration file, created by +# sphinx-quickstart on Thu Jun 29 15:43:19 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# 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 subprocess +import sys +from datetime import date + +import sphinx_fontawesome + +# sys.path.insert(0, os.path.abspath('../')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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.napoleon', + 'sphinx.ext.intersphinx', + 'sphinx.ext.coverage', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sphinx.ext.doctest', + 'sphinx.ext.githubpages', + 'sphinx_fontawesome', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'CodeGrade Emacs Plugin' +copyright = str(date.today().year) + ', CodeGrade' +author = 'CodeGrade Team' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. + +with open("../codegra.el", 'r') as f: + data = f.read() + needle = '\n;; Version: ' + version = data[data.find(needle) + len(needle):].split()[0] + +# The full version, including alpha/beta/rc tags. +release = version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', ''] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +# -- 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' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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'] + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'CodeGradeel' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [(master_doc, 'CodeGrade.tex', 'CodeGrade Documentation', + author, 'manual'), ] + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, 'codegrade', 'CodeGrade Documentation', [author], + 1)] + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'CodeGrade', 'CodeGrade Documentation', author, 'CodeGrade', + 'One line description of project.', 'Miscellaneous'), +] + +todo_include_todos = True + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + 'https://docs.python.org/3': None, + 'http://werkzeug.pocoo.org/docs/latest/': None, + 'http://flask.pocoo.org/docs/latest/': None, + 'http://sqlalchemy-utils.readthedocs.io/en/latest': None, +} + +html_favicon = '_static/_images/favicon.ico' +html_logo = '_static/_images/logo.svg' +html_theme_options = { + 'logo_only': True, +} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..94d292e --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,25 @@ +.. CodeGra.de documentation master file, created by + sphinx-quickstart on Thu Jun 29 15:43:19 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. +.. rst-class:: fa fa-fontawesome + +CodeGrade Emacs Plug-in +====================================== + +Even though the CodeGrade filesystem works together with any editor by manually +editing its special files, it is recommended to use it in combination with +editor plugins. CodeGrade offers a plugin for the +`Emacs `__ editor. This plugin is +also known as *CodeGra.el*. + +The code of the CodeGrade Emacs Plug-in is open-source and can be found on +`Github `__. + +.. toctree:: + :maxdepth: 2 + :caption: CodeGrade Emacs Plug-in + + install + usage + Back to Filesystem Documentation diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..beace8c --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,19 @@ +Installation +============= +The CodeGrade filesystem has to be installed and both the ``cgfs`` and the +``cgapi-consumer`` helper program must be available from the user's ``$PATH`` to +successfully install and use the CodeGrade editor plugins. + +After the Filesystem is successfully installed clone +`this `__ repository to a +local folder (using the ``git clone git@github.com:CodeGra-de/CodeGra.el.git`` +commmand) and add this folder to your ``load-path`` in emacs. + +After doing this you can add ``(require 'codegrade)`` to your emacs config. + +.. note:: + + In addition to the general dependencies for all plugins, the Emacs plugin + depends on the `switch-buffer-functions + `__ package, which can + be installed using ``MELPA``. diff --git a/docs/sphinx/seed_data b/docs/sphinx/seed_data new file mode 120000 index 0000000..4e93928 --- /dev/null +++ b/docs/sphinx/seed_data @@ -0,0 +1 @@ +../../seed_data \ No newline at end of file diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..77c3dc1 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,48 @@ +Using the Emacs Plugin +======================== +After installation, the CodeGrade Emacs plugin can be used. The plugin offers +two main functions: editing rubrics and giving line feedback. + +.. warning:: + + It is important to note that this package does not yet check if the + file-system if mounted in ``--fixed`` mode, please make sure it is when + giving line feedback. + +Editing rubric +--------------- +To edit a rubric you call the ``codegrade-open-rubric`` function. This opens a +rubric in a new buffer with the major mode ``codegrade-rubric-mode`` that you +can edit. To toggle a rubric item you can call ``codegrade-toggle-rubric-item`` +which is bound to :kbd:`c` and :kbd:`,` by default in the +``codegrade-rubric-mode``. You can goto the next item with +``codegrade-goto-next-item`` (bound to :kbd:`n`) and to the previous item with +``codegrade-goto-previous-item`` (bound to :kbd:`p`). To goto next or previous +headers use the ``codegrade-goto-*-header`` functions (bound to :kbd:`N` and +:kbd:`P` by default). + +To quit this rubric you should use the ``codegrade-rubric-close`` function, +bound to :kbd:`q`. + +.. note:: + + The opened buffer follows you around. So if you open another submission by + another user the rubric buffer automatically updates. See the first line of + this buffer to see which person you are grading. + +Line feedback +-------------- +To edit line feedback you can call the ``codegrade-add-feedback`` function on a +line. This opens a new buffer in the ``codegrade-feedback-mode`` mode. You can +save the contents in this buffer and quit by calling +``codegrade-feedback-close`` (bound to :kbd:`C-c C-c` by default). To quit +without saving you can call ``codegrade-feedback-quit``, bound to :kbd:`C-c C-k` +by default. + +You can also delete a line of feedback by calling ``codegrade-delete-feedback``. +To see the feedback of a line you can call ``codegrade-get-feedback``. + +Giving grades +-------------- +You can also give a grade using this plugin. Simply call +``codegrade-give-grade`` and input a number between 0 and 10. diff --git a/docs_requirements.txt b/docs_requirements.txt new file mode 100644 index 0000000..299e1f8 --- /dev/null +++ b/docs_requirements.txt @@ -0,0 +1,4 @@ +sphinx-fontawesome==0.0.6 +sphinx-rtd-theme==0.4.2 +Sphinx==1.8.1 +travis-sphinx