From fad114ac16bd111c38bd628fea276c7c4a664a16 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 10:46:34 -0400 Subject: [PATCH 01/24] Add pyproject.toml --- pyproject.toml | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 pyproject.toml diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..0404a81 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,33 @@ +[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", +] + +[project.urls] +Home = "https://github.com/ResearchCodeReviewCommunity/dev-review" From d8c009fb6cf61641be61477387e12b7fd65a6414 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 10:46:44 -0400 Subject: [PATCH 02/24] Add .readthedocs.yaml --- .readthedocs.yaml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 .readthedocs.yaml 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 From 89e7f08f3cd2f748967141d6a7593a5ed2623e2b Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 11:16:50 -0400 Subject: [PATCH 03/24] Add noxfile.py --- noxfile.py | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 noxfile.py 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") From d2ca7a9112bd2b607a48407f06ad92efa428e8a6 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 11:23:36 -0400 Subject: [PATCH 04/24] Add dummy package src/dev_review --- src/dev_review/__about__.py | 38 +++++++++++++++++++++++++++++++++++++ src/dev_review/__init__.py | 0 2 files changed, 38 insertions(+) create mode 100644 src/dev_review/__about__.py create mode 100644 src/dev_review/__init__.py 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 From 842a11d5d4bc8fc0a5a13cad906def1d088ba31d Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 11:43:40 -0400 Subject: [PATCH 05/24] Add Python + Mac OS related entries to .gitignore --- .gitignore | 11 +++++++++++ 1 file changed, 11 insertions(+) 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 From b2aeeda80dbdb099f990ad49782615eb0c9f2af7 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 11:44:00 -0400 Subject: [PATCH 06/24] Add initial output of sphinx-quickstart in doc/ --- docs/Makefile | 20 ++++++++++++++++++ docs/conf.py | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 20 ++++++++++++++++++ docs/make.bat | 35 ++++++++++++++++++++++++++++++++ 4 files changed, 130 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat 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..ddb2c7f --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,55 @@ +# 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 = 'dev_review' +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 = [ +] + +# 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 = ['_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 = '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/index.rst b/docs/index.rst new file mode 100644 index 0000000..5331228 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. dev_review documentation master file, created by + sphinx-quickstart on Mon Apr 4 11:41:47 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to dev_review's documentation! +====================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` 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 From 8579e872181e9b4b9b76b499cf7d97c6da39dd01 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 11:46:29 -0400 Subject: [PATCH 07/24] Add extensions + theme to doc/conf.py --- docs/conf.py | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ddb2c7f..5da7aee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,11 +31,25 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'myst_parser', + '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'] + # 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. @@ -47,9 +61,9 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +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'] \ No newline at end of file +html_static_path = ['_static'] From 56f4c28bf254873dbfbb41999849b5eb5dcbdbcf Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 11:59:07 -0400 Subject: [PATCH 08/24] Add 'sphinxcontrib-mermaid' to 'docs' in pyproject.toml --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 0404a81..0750321 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,6 +27,7 @@ docs = [ "sphinx-copybutton >=0.4.0", "sphinx-autobuild >= 2021.3.14", "sphinx-book-theme>=0.3.2", + "sphinxcontrib-mermaid>=0.7.1", ] [project.urls] From 0f84c4d11db8ffb9fbf1b221868ef556b49ac3ab Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 11:59:25 -0400 Subject: [PATCH 09/24] Add 'sphinxcontrib.mermaid' to extensions in doc/conf.py --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 5da7aee..d589ef5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,6 +32,7 @@ # ones. extensions = [ 'myst_parser', + 'sphinxcontrib.mermaid', 'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx_copybutton', @@ -50,6 +51,8 @@ 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. From 9037d03912503abf640759f5a2b75b4a2d16541e Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 12:05:06 -0400 Subject: [PATCH 10/24] Change master_doc to 'index' in docs/conf.py, gets build to work --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index d589ef5..e4d454f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,7 +51,7 @@ source_suffix = ['.rst', '.md'] -master_doc = '_index' +master_doc = 'index' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. From 980a37ce7f04b09555d518ad25a4777e99500365 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 12:24:48 -0400 Subject: [PATCH 11/24] Change project name in docs/conf.py --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index e4d454f..d5665af 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,7 @@ # -- Project information ----------------------------------------------------- -project = 'dev_review' +project = 'Code Review During Research' copyright = '2022, Research Code Review Community' author = 'Research Code Review Community' From d617cdd523f1a33bbddf22452a3c880edcc63701 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Sun, 5 Jun 2022 17:46:07 -0400 Subject: [PATCH 12/24] Move all of site/content/ -> docs/ --- {site/content => docs}/_index.md | 0 {site/content => docs}/flowcharts/high-level.md | 0 {site/content => docs}/glossary.md | 0 {site/content => docs}/guidelines/approach.md | 0 .../content => docs}/guidelines/points-to-check-for-reviewers.md | 0 {site/content => docs}/recipes/explain_code_structure.md | 0 {site/content => docs}/recipes/find_a_reviewer.md | 0 {site/content => docs}/recipes/lonecoder.md | 0 {site/content => docs}/recipes/meet_and_agree_on_objectives.md | 0 {site/content => docs}/recipes/perform_code_review.md | 0 {site/content => docs}/recipes/recipe_template.md | 0 {site/content => docs}/refs-related.md | 0 12 files changed, 0 insertions(+), 0 deletions(-) rename {site/content => docs}/_index.md (100%) rename {site/content => docs}/flowcharts/high-level.md (100%) rename {site/content => docs}/glossary.md (100%) rename {site/content => docs}/guidelines/approach.md (100%) rename {site/content => docs}/guidelines/points-to-check-for-reviewers.md (100%) rename {site/content => docs}/recipes/explain_code_structure.md (100%) rename {site/content => docs}/recipes/find_a_reviewer.md (100%) rename {site/content => docs}/recipes/lonecoder.md (100%) rename {site/content => docs}/recipes/meet_and_agree_on_objectives.md (100%) rename {site/content => docs}/recipes/perform_code_review.md (100%) rename {site/content => docs}/recipes/recipe_template.md (100%) rename {site/content => docs}/refs-related.md (100%) diff --git a/site/content/_index.md b/docs/_index.md similarity index 100% rename from site/content/_index.md rename to docs/_index.md diff --git a/site/content/flowcharts/high-level.md b/docs/flowcharts/high-level.md similarity index 100% rename from site/content/flowcharts/high-level.md rename to docs/flowcharts/high-level.md 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/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 100% rename from site/content/recipes/find_a_reviewer.md rename to docs/recipes/find_a_reviewer.md 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 From 196fa975228621482e4c1dc62ed9b56f79db55ba Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 11:53:36 -0400 Subject: [PATCH 13/24] Delete docs/index.rst --- docs/index.rst | 20 -------------------- 1 file changed, 20 deletions(-) delete mode 100644 docs/index.rst diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 5331228..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. dev_review documentation master file, created by - sphinx-quickstart on Mon Apr 4 11:41:47 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to dev_review's documentation! -====================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` From 6eb13194af626e3aace8d57ba6a76cf0a211286a Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 12:01:12 -0400 Subject: [PATCH 14/24] Use myst 'mermaid' directive in docs/_index.md --- docs/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_index.md b/docs/_index.md index cdcee20..9dd14ba 100644 --- a/docs/_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) From 93b2a767d494ae0e59d92c2eced9e18697d49ba3 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 12:01:52 -0400 Subject: [PATCH 15/24] Rename docs/_index.md -> docs/index.md --- docs/{_index.md => index.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{_index.md => index.md} (100%) diff --git a/docs/_index.md b/docs/index.md similarity index 100% rename from docs/_index.md rename to docs/index.md From 08650ef02b72b4939fbe5e29281da31f3a608d22 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 12:09:10 -0400 Subject: [PATCH 16/24] Fix mermaid chart and links in docs/flowcharts/high-level.md --- docs/flowcharts/high-level.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/flowcharts/high-level.md b/docs/flowcharts/high-level.md index eb4884f..80b47e4 100644 --- a/docs/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 "./high-level.html#find-a-reviewer" "Find a reviewer" + click C "./high-level.html#meet-and-agree-on-objectives" "Meet and agree on objectives" + click D,E,F,G "./high-level.html#perform-code-review" "Perform Code Review" + click I "./high-level.html#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 From 96dd4b2793d0e1f9037313c9b715fafe4a4a86a6 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Mon, 4 Apr 2022 12:17:57 -0400 Subject: [PATCH 17/24] Fix internal links in docs/recipes/find_a_reviewer.md --- docs/recipes/find_a_reviewer.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/recipes/find_a_reviewer.md b/docs/recipes/find_a_reviewer.md index a5fe695..0dc8b94 100644 --- a/docs/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 From 57169ae182baf4f199492165509aaa29bf0bba43 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Sun, 5 Jun 2022 17:50:15 -0400 Subject: [PATCH 18/24] Remove .github/workflows/deploy.yml -- no longer used --- .github/workflows/deploy.yml | 39 ------------------------------------ 1 file changed, 39 deletions(-) delete mode 100644 .github/workflows/deploy.yml 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 From 0dd8eb087c534381d426f44d0605f0c6b2a87f70 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Sun, 5 Jun 2022 18:03:39 -0400 Subject: [PATCH 19/24] Rewrite README.md to use nox + sphinx --- README.md | 65 +++++++++++++++++++++++++------------------------------ 1 file changed, 29 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 5784932..b54fed8 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,57 @@ # 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: +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) ## 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 +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 locally, 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 +sphinx-build -nW --keep-going -b html doc/ doc/_build/html +cd doc/_build/html; python -m http.server;cd ../../.. ``` 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: From 98056980267fa9bd6533a13c74a160bb9737beb5 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Fri, 29 Jul 2022 15:59:02 -0400 Subject: [PATCH 20/24] Add alternative method for installing pipx to README Co-authored-by: Matthew --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b54fed8..501e7b8 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ There are many ways to install but we recommend the following: - macOS/Linux ``` -brew install pipx +brew install pipx # or `python3 -m pip install --user pipx` pipx install nox nox -s dev ``` From 9ca3a149ec5d938331cdf2f58eaabd079ba686cc Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Fri, 29 Jul 2022 16:00:08 -0400 Subject: [PATCH 21/24] Add tree diagram of project to README Co-authored-by: Matthew --- README.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 501e7b8..05a8347 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,26 @@ 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 +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 We use [`nox`](https://nox.thea.codes/en/stable/) From 49117e00cd6a93fb9c11a05d6708eac4deb2c0d9 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Fri, 29 Jul 2022 16:00:36 -0400 Subject: [PATCH 22/24] Slight rewording in README Co-authored-by: Matthew --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 05a8347..19eed8f 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ git clone git@github.com:ResearchCodeReviewCommunity/dev-review.git ``` ## Development -To preview changes locally, you can build and serve the website locally. +To preview changes, you can build and serve the website locally. ``` sphinx-build -nW --keep-going -b html doc/ doc/_build/html From 4cfc4eab8f94cd189e4e8b3791770e2facdab1ba Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Fri, 29 Jul 2022 16:01:24 -0400 Subject: [PATCH 23/24] Show serving docs with nox in README Co-authored-by: Matthew --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 19eed8f..937446d 100644 --- a/README.md +++ b/README.md @@ -59,8 +59,7 @@ git clone git@github.com:ResearchCodeReviewCommunity/dev-review.git To preview changes, you can build and serve the website locally. ``` -sphinx-build -nW --keep-going -b html doc/ doc/_build/html -cd doc/_build/html; python -m http.server;cd ../../.. +nox -s docs -- serve ``` Open your favorite web-browser using the following url: From 40badfbdc40de158c3081ca65bc1b4c19e134342 Mon Sep 17 00:00:00 2001 From: David Nicholson Date: Fri, 29 Jul 2022 16:08:57 -0400 Subject: [PATCH 24/24] Use relative references in docs/flowcharts/high-level.md Co-authored-by: Matthew --- docs/flowcharts/high-level.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/flowcharts/high-level.md b/docs/flowcharts/high-level.md index 80b47e4..6e5e03a 100644 --- a/docs/flowcharts/high-level.md +++ b/docs/flowcharts/high-level.md @@ -17,10 +17,10 @@ graph TD; H -- Yes --> D H -- No --> I([Finish]) - click B "./high-level.html#find-a-reviewer" "Find a reviewer" - click C "./high-level.html#meet-and-agree-on-objectives" "Meet and agree on objectives" - click D,E,F,G "./high-level.html#perform-code-review" "Perform Code Review" - click I "./high-level.html#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;