diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml deleted file mode 100644 index fbc0262..0000000 --- a/.github/workflows/deploy.yml +++ /dev/null @@ -1,39 +0,0 @@ -name: Deploy website to gh-pages branch - -on: - push: - branches: - - main - -jobs: - - build-and-deploy: - - runs-on: ubuntu-20.04 - - steps: - - - name: checkout repo & submodules - uses: actions/checkout@v2 - with: - submodules: true - fetch-depth: 0 - - - name: Build the website - run: | - wget https://github.com/gohugoio/hugo/releases/download/v0.85.0/hugo_extended_0.85.0_Linux-64bit.deb - sudo dpkg -i hugo_extended_0.85.0_Linux-64bit.deb - hugo - working-directory: site - - - name: Deploy contents of `site/public` to gh-pages docs dir - run: | - git config user.name "github-action" - git config user.email "github-action" - git checkout gh-pages - rm -rf docs/* - cp -rT site/public docs - rm -rf site - git add --all - git commit -m "deploy website" || echo "No changes to commit" - git push diff --git a/.gitignore b/.gitignore index 7c0899b..2997211 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,14 @@ site/resources/_gen/* .idea ## vscode .vscode + +# Python +*__pycache__* +*egg-info/ +dist/ +build/ +.venv +docs/_build + +# Mac +.DS_Store diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..000d330 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,20 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-20.04 + tools: + python: "3.8" + +sphinx: + configuration: docs/conf.py + +python: + install: + - method: pip + path: . + extra_requirements: + - docs diff --git a/README.md b/README.md index 5784932..937446d 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,74 @@ # Code Review During Development -This repository is automatically built from [markdown](https://commonmark.org/) files by [Hugo](https://gohugo.io/) using [GitHub Actions](https://github.com/features/actions). -This site uses the Hugo [LoveIt](https://hugoloveit.com/) theme. +This repository is automatically built from [markdown](https://commonmark.org/) files by [Sphinx](https://www.sphinx-doc.org/) and the [MyST parser](https://myst-parser.readthedocs.io) +using [ReadTheDocs](https://readthedocs.org/). +This site uses the [Sphinx Book](https://sphinx-book-theme.readthedocs.io) theme. This site is available here: https://researchcodereviewcommunity.github.io/dev-review/ -The following branches in this repository are important: -- `main`: the markdown files corresponding to the current live version of the website -- `gh-pages`: the static html site, automatically built by Hugo on new commits to `main` by [this script](.github/workflows/deploy.yml) +The content of the website is contained in markdown files located in the `docs/` folder and are structured like so + +~~~text +docs/ +├── flowcharts <-- any mermaid flowcharts used in multiple locations +│   └── high-level.md +├── glossary.md <-- a glossary of important terms for code review +├── guidelines <-- more general guidelines for code review apart from the more prescriptive recipes +│   ├── approach.md +│   └── points-to-check-for-reviewers.md +├── index.md <-- the landing page of the website +├── recipes <-- our suggested steps to follow during the code review process +│   ├── explain_code_structure.md +│   ├── find_a_reviewer.md +│   ├── lonecoder.md +│   ├── meet_and_agree_on_objectives.md +│   ├── perform_code_review.md +│   └── recipe_template.md +└── refs-related.md <-- references for material related to code review +~~~ ## Dependencies -Install hugo extended dependency. -The "extended" hugo version is required to enable some features of [the LoveIt theme](https://hugoloveit.com/), such as mermaid diagrams. -See commands to install hugo based on your Operating system. -- macOS +We use [`nox`](https://nox.thea.codes/en/stable/) +as a task-runner to create development environments +and to build the docs. +There are many ways to install but we recommend the following: +1. use a system package manager to install `pipx` +2. use `pipx` to install `nox` so you can use it across projects +3. finally ask `nox` to create a development environment + +- macOS/Linux ``` -brew install hugo +brew install pipx # or `python3 -m pip install --user pipx` +pipx install nox +nox -s dev ``` - Windows ``` -choco install hugo -confirm -``` -- GNU/Linux (Debian and Ubuntu) +choco install pipx -confirm +pipx install nox +nox -s dev ``` -snap install hugo --channel=extended -``` - -See [documentation](https://gohugo.io/getting-started/installing/) for other options and furhter instructions. ## Clone this repository -After generating your SSH keys as suggested [here](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). +After generating your SSH keys as suggested [here](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). You can then clone the repository by typing (or copying) the following line in a terminal at your preferred path in your machine: ``` -git clone --recurse-submodules git@github.com:ResearchCodeReviewCommunity/dev-review.git +git clone git@github.com:ResearchCodeReviewCommunity/dev-review.git ``` -If you've cloned this repo without the `--recurse-submodules` options, then you can initialise your local git submodule config with -``` -git submodule init -``` -and update it with -``` -git submodule update -``` +## Development +To preview changes, you can build and serve the website locally. -## Development -To preview changes locally, you can build and serve the website locally. -The `disableFastRender` option is required to render some features brought by the LoveIt theme, such as mermaid diagrams. ``` -cd site/ && hugo serve --disableFastRender +nox -s docs -- serve ``` Open your favorite web-browser using the following url: ``` -Web Server is available at http://localhost:1313/dev-review/ (bind address 127.0.0.1) -Press Ctrl+C to stop +Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... ``` -See [Launching the website locally (hugoloveit.com)](https://hugoloveit.com/theme-documentation-basics/#25-launching-the-website-locally) for further information. ## Contributing -Commit changes to any other branch than `main` or `gh-pages`, open a pull request and request for reviews as common practice following the [pull request workflow with git](https://medium.com/@urna.hybesis/pull-request-workflow-with-git-6-steps-guide-3858e30b5fa4). -Once your changes are merged into `main` branch, the site will be automatically built and deployed and will be live roughly 1 minute later. +Commit changes to any other branch than `main`, open a pull request and request for reviews as common practice following the [pull request workflow with git](https://medium.com/@urna.hybesis/pull-request-workflow-with-git-6-steps-guide-3858e30b5fa4). +Once your changes are merged into `main` branch, the site will be automatically built and deployed and will be live roughly 1 minute later. -:warning: **Do not commit directly to `main` or `gh-pages`.** :warning: +:warning: **Do not commit directly to `main`.** :warning: diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +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/conf.py b/docs/conf.py new file mode 100644 index 0000000..d5665af --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,72 @@ +# 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('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Code Review During Research' +copyright = '2022, Research Code Review Community' +author = 'Research Code Review Community' + +# The full version, including alpha/beta/rc tags +release = '0.1.0' + + +# -- 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 = [ + 'myst_parser', + 'sphinxcontrib.mermaid', + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx_copybutton', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.mathjax', + 'sphinx.ext.napoleon', + 'sphinxext.opengraph', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +source_suffix = ['.rst', '.md'] + +master_doc = 'index' + +# 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_book_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'] diff --git a/site/content/flowcharts/high-level.md b/docs/flowcharts/high-level.md similarity index 92% rename from site/content/flowcharts/high-level.md rename to docs/flowcharts/high-level.md index eb4884f..6e5e03a 100644 --- a/site/content/flowcharts/high-level.md +++ b/docs/flowcharts/high-level.md @@ -3,7 +3,7 @@ Here's a high-level view of a workflow researchers can follow to make code review part of their development process. -{{< mermaid >}} +```{mermaid} %% codereview mermaid graph TD; Link(Click on orange boxes for more detail) @@ -17,15 +17,15 @@ graph TD; H -- Yes --> D H -- No --> I([Finish]) - click B "./#find-a-reviewer" "Find a reviewer" - click C "./#meet-and-agree-on-objectives" "Meet and agree on objectives" - click D,E,F,G "./#perform-code-review" "Perform Code Review" - click I "./#finish" "Finish" + click B "#find-a-reviewer" "Find a reviewer" + click C "#meet-and-agree-on-objectives" "Meet and agree on objectives" + click D,E,F,G "#perform-code-review" "Perform Code Review" + click I "#finish" "Finish" classDef default fill:#8EB6DE,stroke:#162D4D,stroke-width:2px,color:#162D4D; classDef linkedBox fill:#FABB00,stroke:#000,stroke-width:2px,color:#000; class Link,B,C,D,E,F,G,I linkedBox -{{< /mermaid >}} +``` ### Find a reviewer diff --git a/site/content/glossary.md b/docs/glossary.md similarity index 100% rename from site/content/glossary.md rename to docs/glossary.md diff --git a/site/content/guidelines/approach.md b/docs/guidelines/approach.md similarity index 100% rename from site/content/guidelines/approach.md rename to docs/guidelines/approach.md diff --git a/site/content/guidelines/points-to-check-for-reviewers.md b/docs/guidelines/points-to-check-for-reviewers.md similarity index 100% rename from site/content/guidelines/points-to-check-for-reviewers.md rename to docs/guidelines/points-to-check-for-reviewers.md diff --git a/site/content/_index.md b/docs/index.md similarity index 98% rename from site/content/_index.md rename to docs/index.md index cdcee20..9dd14ba 100644 --- a/site/content/_index.md +++ b/docs/index.md @@ -20,14 +20,14 @@ accessible by researchers at all levels, from research students to senior professors, whether they are new to programming or software engineering experts.** -{{< mermaid >}} +```{mermaid} graph TD; A(Initial reviewer-author meeting) --> B(Reviewer examines code) B --> C(Reviewer compiles suggestions) C --> D(Author and reviewer go over code) D --> E(Author improves code) E --> B -{{< /mermaid >}} +``` ## Getting Started Please see [this page](flowcharts/high-level) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/site/content/recipes/explain_code_structure.md b/docs/recipes/explain_code_structure.md similarity index 100% rename from site/content/recipes/explain_code_structure.md rename to docs/recipes/explain_code_structure.md diff --git a/site/content/recipes/find_a_reviewer.md b/docs/recipes/find_a_reviewer.md similarity index 96% rename from site/content/recipes/find_a_reviewer.md rename to docs/recipes/find_a_reviewer.md index a5fe695..0dc8b94 100644 --- a/site/content/recipes/find_a_reviewer.md +++ b/docs/recipes/find_a_reviewer.md @@ -40,7 +40,8 @@ satisfy to make a code review worthwhile for both parties, and there are some places to search for reviewers that have a higher chance of yielding someone that fulfills these criteria. Let's look at these now. -### Step 1: Places to Look {#search} +(find-reviewer-search)= +### Step 1: Places to Look When looking for a reviewer, your first port of call should almost always be your own research group. Your colleagues are the most likely to be using the @@ -76,7 +77,7 @@ review in your research group, that problem will probably resurface here. Another great place to search within your institution or region are language or library-specific community groups (e.g. a Python or R User Group). This can help ensure the reviewer has experience with the same or similar tools you use. -Before [making your advertisement](#contact), consider asking one of the +Before {ref}`making your advertisement `, consider asking one of the community managers or someone you know in the community whether code review is something that has been done before or others might be interested in. Just as in the case with colleagues, you will be relying on people to volunteer their @@ -106,7 +107,8 @@ determine whether it could suit your needs. Anecdotally, StackExchange sites can -### Step 2: Criteria for Screening {#criteria} +(find-reviewer-criteria)= +### Step 2: Criteria for Screening Before contacting a potential reviewer, consider whether they are a good fit to the code being reviewed. Ideally, a reviewer will have some experience in the @@ -138,7 +140,8 @@ community to advertsie in. library or tool and how essential it is to the functionality of your code. -### Step 3: Contact candidate or advertise {#contact} +(find-reviewer-contact)= +### Step 3: Contact candidate or advertise Everyone has their own way of writing messages, and we don't want to be too prescriptive about how you reach out to a potential reviewer. If you already @@ -158,12 +161,13 @@ you compose: identify the reasons that motivated you to get your code reviewed. - A brief summary of what your code does and any particular aspects you want addressed. -- [Any of the criteria for a suitable reviewer](#criteria) that you weren't - able to answer yourself before reaching out. +- {ref}`Any of the criteria for a suitable reviewer ` + that you weren't able to answer yourself before reaching out. - An idea of the time commitment (**TODO** what is our estimate for how long the whole process will take?) -### Step 4: Rinse and Repeat {#repeat} +(find-reviewer-repeat)= +### Step 4: Rinse and Repeat Loop through steps 1 to 3 until you get a bite. Once you have your reviewer, proceed to the [next step](meet_and_agree_on_objectives) and arrange a meeting diff --git a/site/content/recipes/lonecoder.md b/docs/recipes/lonecoder.md similarity index 100% rename from site/content/recipes/lonecoder.md rename to docs/recipes/lonecoder.md diff --git a/site/content/recipes/meet_and_agree_on_objectives.md b/docs/recipes/meet_and_agree_on_objectives.md similarity index 100% rename from site/content/recipes/meet_and_agree_on_objectives.md rename to docs/recipes/meet_and_agree_on_objectives.md diff --git a/site/content/recipes/perform_code_review.md b/docs/recipes/perform_code_review.md similarity index 100% rename from site/content/recipes/perform_code_review.md rename to docs/recipes/perform_code_review.md diff --git a/site/content/recipes/recipe_template.md b/docs/recipes/recipe_template.md similarity index 100% rename from site/content/recipes/recipe_template.md rename to docs/recipes/recipe_template.md diff --git a/site/content/refs-related.md b/docs/refs-related.md similarity index 100% rename from site/content/refs-related.md rename to docs/refs-related.md diff --git a/noxfile.py b/noxfile.py new file mode 100644 index 0000000..c179cc7 --- /dev/null +++ b/noxfile.py @@ -0,0 +1,55 @@ +import os +import pathlib + +import nox + +VENV_DIR = pathlib.Path('./.venv').resolve() + + +@nox.session +def dev(session: nox.Session) -> None: + """ + Sets up a python development environment for the project. + This session will: + - Create a python virtualenv for the session + - Install the `virtualenv` cli tool into this environment + - Use `virtualenv` to create a global project virtual environment + - Invoke the python interpreter from the global project environment to install + the project and all it's development dependencies. + """ + + session.install("virtualenv") + # VENV_DIR here is a pathlib.Path location of the project virtualenv + # e.g. .venv + session.run("virtualenv", os.fsdecode(VENV_DIR), silent=True) + + python = os.fsdecode(VENV_DIR.joinpath("bin/python")) + + # Use the venv's interpreter to install the project along with + # all it's dev dependencies, this ensures it's installed in the right way + session.run(python, "-m", "pip", "install", "-e", ".[dev,test,doc]", external=True) + + +@nox.session +def docs(session: nox.Session) -> None: + """ + Build the docs. Pass "serve" to serve. Pass "autobuild" to run ``sphinx-autobuild``. + """ + if session.posargs: + if "autobuild" in session.posargs: + # autobuild does the build bit, too + session.install(".[docs]") + session.run("sphinx-autobuild", "docs", "docs/_build/html") + elif "serve" in session.posargs: + session.install(".[docs]") + session.chdir("docs") + session.run("sphinx-build", "-M", "html", ".", "_build") + + print("Launching docs at http://localhost:8000/ - use Ctrl-C to quit") + session.run("python", "-m", "http.server", "8000", "-d", "_build/html") + else: + print("Unsupported argument to docs") + else: + session.install(".[docs]") + session.chdir("docs") + session.run("sphinx-build", "-M", "html", ".", "_build") diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..0750321 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,34 @@ +[build-system] +requires = ["flit_core >=3.2,<4"] +build-backend = "flit_core.buildapi" + +[project] +name = "dev_review" +description = "guide to code review during research" +version = "0.1.0" +authors = [{name = "Research Code Review Community", email = "fergus.cooper@cs.ox.ac.uk"}] +readme = "README.md" +classifiers = [ + 'License :: OSI Approved :: BSD License', + 'Development Status :: 5 - Production/Stable', + 'Programming Language :: Python', + 'Programming Language :: Python :: 3', + 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: Implementation :: CPython', +] + +[project.optional-dependencies] +docs = [ + "myst-parser >=0.17.0", + "Sphinx>=3.4.3", + "sphinxext-opengraph >=0.5.1", + "sphinx-copybutton >=0.4.0", + "sphinx-autobuild >= 2021.3.14", + "sphinx-book-theme>=0.3.2", + "sphinxcontrib-mermaid>=0.7.1", +] + +[project.urls] +Home = "https://github.com/ResearchCodeReviewCommunity/dev-review" diff --git a/src/dev_review/__about__.py b/src/dev_review/__about__.py new file mode 100644 index 0000000..66065c5 --- /dev/null +++ b/src/dev_review/__about__.py @@ -0,0 +1,38 @@ +import os.path + +__all__ = [ + "__title__", + "__summary__", + "__uri__", + "__version__", + "__commit__", + "__author__", + "__email__", + "__license__", + "__copyright__", +] + + +try: + base_dir = os.path.dirname(os.path.abspath(__file__)) +except NameError: + base_dir = None + + +__title__ = "dev_review" +__summary__ = "guide to code review during research" +__uri__ = "https://github.com/ResearchCodeReviewCommunity/dev-review" + +__version__ = "0.1.0" + +if base_dir is not None and os.path.exists(os.path.join(base_dir, ".commit")): + with open(os.path.join(base_dir, ".commit")) as fp: + __commit__ = fp.read().strip() +else: + __commit__ = None + +__author__ = "Research Code Review Community" +__email__ = "fergus.cooper@cs.ox.ac.uk" + +__license__ = "MIT" +__copyright__ = "2020-present %s" % __author__ diff --git a/src/dev_review/__init__.py b/src/dev_review/__init__.py new file mode 100644 index 0000000..e69de29