v3.0.0

.gitignore

@@ -1,3 +1,5 @@
+.DS_store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.readthedocs.yml

@@ -0,0 +1,15 @@
+build:
+  image: latest
+
+python:
+  version: 3.7
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - develop
+
+sphinx:
+  builder: dirhtml
+
+version: 2

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = lib50
+SOURCEDIR     = source
+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)

docs/source/api.rst

@@ -0,0 +1,25 @@
+.. _api:
+
+API docs
+========
+
+.. _lib50:
+
+lib50
+*******
+
+.. automodule:: lib50
+  :members:
+  :imported-members:
+
+lib50.config
+************
+
+.. automodule:: lib50.config
+  :members:
+
+lib50.crypto
+************
+
+.. automodule:: lib50.crypto
+  :members:

docs/source/conf.py

@@ -0,0 +1,32 @@
+import os
+import sys
+import time
+
+_tool = "lib50"
+
+# Add path to module for autodoc
+sys.path.insert(0, os.path.abspath(f'../../{_tool}'))
+
+# Include __init__ in autodoc
+# Source: https://stackoverflow.com/questions/5599254/how-to-use-sphinxs-autodoc-to-document-a-classs-init-self-method
+def skip(app, what, name, obj, would_skip, options):
+    if name == "__init__":
+        return False
+    return would_skip
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip)
+
+extensions = ['sphinx.ext.autodoc']
+
+html_css_files = ["https://cs50.readthedocs.io/_static/custom.css?" + str(round(time.time()))]
+html_js_files = ["https://cs50.readthedocs.io/_static/custom.js?" + str(round(time.time()))]
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "display_version": False,
+    "prev_next_buttons_location": False,
+    "sticky_navigation": False
+}
+html_title = f'{_tool} Docs'
+
+project = f'{_tool}'

docs/source/index.rst

@@ -0,0 +1,64 @@
+``lib50``
+===========
+
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+   :caption: Contents:
+
+   api
+
+.. Indices and tables
+.. ==================
+
+.. * :ref:`genindex`
+.. * :ref:`api`
+.. * :ref:`modindex`
+.. * :ref:`search`
+
+
+lib50 is CS50's library for common functionality shared between its tools. The library is, like most of CS50's projects, open-source, but its intention is to serve as an internal library for CS50's own tools. As such it is our current recommendation to not use lib50 as a dependency of one's own projects.
+
+The following concepts live primarily in lib50:
+
+* CS50 slugs
+* git
+* GitHub
+* ``.cs50.yml`` config files
+* signing and verification of payloads
+
+
+Design
+******
+
+To promote reuse of functionality across CS50 tools, lib50 is designed to be tool agnostic. lib50 provides just the core functionality, but the semantics of that functionality are left up to the tool. For instance, submit50 adds the notion of a submission to a push, whereas it is the ``lib50.push`` function that ultimately handles the workflow with git and GitHub. Or per another example, lib50 provides the functionality to parse and validate ``.cs50.yml`` configuration files, but each individual tool (check50, submit50 and lab50) specifies their own options and handles their own logic.
+
+With the overarching design goal to make it easy to add to or to change implementation choices, lib50 abstracts away from implementation details for other CS50 tools. Concepts such as slugs, git, GitHub, and ``.cs50.yml`` live only in lib50. Tools such as check50 interact only with lib50's API at a higher level of abstraction, such as ``lib50.push`` and ``lib50.config.Loader``. The idea being, that there is now a single point of change. For instance, one could add support for another host, such as GitLab perhaps, to ``lib50.push`` and all of CS50's tools could instantly make use of the new host.
+
+
+Installation
+************
+
+First make sure you have Python 3.6 or higher installed. You can download Python |download_python|.
+
+.. |download_python| raw:: html
+
+   <a href="https://www.python.org/downloads/" target="_blank">here</a>
+
+lib50 has a dependency on git, please make sure to |install_git| if git is not already installed.
+
+.. |install_git| raw:: html
+
+   <a href="https://git-scm.com/book/en/v2/Getting-Started-Installing-Git" target="_blank">install git</a>
+
+To install lib50 under Linux / OS X:
+
+.. code-block:: bash
+
+    pip install lib50
+
+Under Windows, please |install_windows_sub|. Then install lib50 within the subsystem.
+
+.. |install_windows_sub| raw:: html
+
+   <a href="https://docs.microsoft.com/en-us/windows/wsl/install-win10" target="_blank">install the Linux subsystem</a>