diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6f51e3d --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.DS_Store +docs/_build/ diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..6e638a9 --- /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 vim-docs.codegra.de diff --git a/README.md b/README.md index d30bd66..ca42e9c 100644 --- a/README.md +++ b/README.md @@ -21,19 +21,19 @@ git clone https://github.com/CodeGra-de/CodeGra.vim ~/.vim/pack/CodeGrade/start Use your package manager of choice, below examples for few popular ones. -```sh -# vim-plug +```vim +" vim-plug call plug#begin() Plug 'CodeGra-de/CodeGra.vim' call plug#end() -# Vundle +" Vundle call vundle#begin() Plugin 'CodeGra-de/CodeGra.vim' call vundle#end() filetype plugin on -# minpac +" minpac call minpac#init() call minpac#add('CodeGra-de/CodeGra.vim') ``` 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..5716a4c --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,29 @@ +.wy-nav-content { + width: 60em; /* Change as you like. */ + max-width: 100% !important; +} + +.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..145279a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,176 @@ +#!/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 Vim 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("../VERSION", 'r') as f: + version = f.read().strip() + +# 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 = 'CodeGradevim' + +# -- 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..5fb8a3d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,24 @@ +.. 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 Vim 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 `Vim `__, +*the editor*. This plugin is also known as *CodeGra.vim*. + +The code of the CodeGrade vim Plug-in is open-source and can be found on +`Github `__. + +.. toctree:: + :maxdepth: 2 + :caption: CodeGrade Vim Plug-in + + install + usage + Back to Filesystem Documentation diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..36a2879 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,38 @@ +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 Vim editor plugin. + +Vim 8 and up +------------- + +Installing the CodeGrade Vim plugin for Vim v8 or higher is done by creating a +CodeGrade bundle directory in your ``.vim`` folder, for instance: +``mkdir ~/.vim/pack/CodeGrade/start``. And then finally cloning the plugin +repository inside this folder via this command: +``git clone https://github.com/CodeGra-de/CodeGra.vim ~/.vim/pack/CodeGrade/start/CodeGra.vim`` + + +Up to Vim 8 +------------ +Installing the CodeGrade Vim plugin for Vim versions up to 8 is done using your +package manager of choice. Some examples for popular package managers + + +.. code-block:: vim + + " vim-plug + call plug#begin() + Plug 'CodeGra-de/CodeGra.vim' + call plug#end() + + " Vundle + call vundle#begin() + Plugin 'CodeGra-de/CodeGra.vim' + call vundle#end() + filetype plugin on + + " minpac + call minpac#init() + call minpac#add('CodeGra-de/CodeGra.vim') 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..b61204f --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,32 @@ +Using the Vim Plugin +======================== +After installation, the mounted folder (e.g. ``mnt/``) can be opened in Vim to +make use of the plugin with the command ``vim mnt/``. +The following commands are available in Vim when editing a file in the CodeGrade +filesystem: + ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| Command | ``--fixed`` | Description | ++======================+=============+==================================================================================================+ +| CGEditFeedback | ✓ | Edit the current submission's global feedback. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| CGEditGrade | ✓ | Edit the current submission's grade. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| CGShowLineFeedback | ✗ | Show the line-feedback for the current buffer in the quickfix list and open the quickfix window. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| CGEditLineFeedback | ✓ | Edit the comment for the current line in the current buffer. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| CGDeleteLineFeedback | ✓ | Delete the comment for the current line in the current buffer. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| CGOpenRubricEditor | ✗ | Edit the rubric of the assignment of the current file. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| CGOpenRubricSelector | ✓ | Open the rubric for the current submission. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| CGRubricPrevSection | ✗ | Go to the previous header in a rubric file. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| CGRubricNextSection | ✗ | Go to the next header in a rubric file. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ +| CGRubricSelectItem | ✓ | Select the rubric item on the current line. | ++----------------------+-------------+--------------------------------------------------------------------------------------------------+ + +.. note:: The ``--fixed`` flag when mounting is required to use specific commands. 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