User PR instructions

docs/source/conf.py

@@ -30,55 +30,57 @@
 # 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.intersphinx']
+extensions = ["sphinx.ext.intersphinx"]
 
-intersphinx_mapping = {'elf': ('https://lookit.readthedocs.io/projects/frameplayer/en/latest/', None)}
+intersphinx_mapping = {
+    "elf": ("https://lookit.readthedocs.io/projects/frameplayer/en/latest/", None)
+}
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+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", ".md"]
 
 from recommonmark.parser import CommonMarkParser
 
 source_parsers = {
-    '.md': CommonMarkParser,
+    ".md": CommonMarkParser,
 }
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'CHS/Lookit'
-copyright = '2017, Center for Open Science and MIT'
-author = 'Center for Open Science, MIT'
+project = "CHS/Lookit"
+copyright = "2017, Center for Open Science and MIT"
+author = "Center for Open Science, MIT"
 
 # 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.
-version = ''
+version = ""
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = ""
 
 # 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'
+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 = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
@@ -89,7 +91,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = "sphinx_rtd_theme"
-#html_theme_path = ["../_themes"]
+# html_theme_path = ["../_themes"]
 
 # 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
@@ -100,20 +102,26 @@
 # 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']
+html_static_path = ["_static"]
 
 # These paths are either relative to html_static_path
 # or fully qualified paths (eg. https://...)
 html_css_files = [
-    'css/lookit.css',
+    "css/lookit.css",
 ]
 
-html_js_files = [
-    'js/links_in_new_tab.js'
-]
+html_js_files = ["js/links_in_new_tab.js"]
 
 
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'lookit-apidoc'
+htmlhelp_basename = "lookit-apidoc"
+
+html_context = {
+    "display_github": True,  # Integrate GitHub
+    "github_user": "lookit",  # Username
+    "github_repo": "lookit-docs",  # Repo name
+    "github_version": "develop",  # Version
+    "conf_py_path": "/docs/source/",  # Path in the checkout to the docs root
+}

docs/source/contributor-guidelines.rst

@@ -22,13 +22,15 @@ To contribute to the `ember-lookit-frameplayer` codebase - e.g., when creating y
 Getting started
 ~~~~~~~~~~~~~~~~~~~
 
-At a high level, we are roughly following a Forking Workflow version of Gitflow `as described here <https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow>`__.
+At a high level, we are roughly following a Forking Workflow version of Gitflow `as described here <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`__.
 
 You should plan to make feature-specific branches off of the ``develop`` branch (for ``lookit-api``, ``lookit-docs``), ``master`` branch (for ``ember-lookit-frameplayer``), or ``main`` branch (for ``lookit-jspsych``) of a local copy of the code running on your own machine. This will keep the codebase as clean as possible.
 
 First create your own fork of ``lookit-api``, ``ember-lookit-frameplayer``, ``lookit-jspsych``, and/or ``lookit-docs``. Follow the directions for installation of ``lookit-api`` or ``ember-lookit-frameplayer`` if needed. 
 
 
+Keep in mind that this project is in active development, and the further your fork is behind our repository, the more complex updating it will be. Please try to keep your code base up to date. If you run into issues with this, feel free to reach out to CHS for help.
+
 Ignoring some files
 ~~~~~~~~~~~~~~~~~~~~
 

docs/source/tutorial-contributing.rst

@@ -14,7 +14,7 @@ Making your first pull request (PR)
 ------------------------------------
 All of the code that makes CHS run is stored on GitHub, which makes it easy to keep track of changes over time and merge changes from many collaborators. There are several code repositories or "repos" that house different pieces of the project. Here we are going to walk through making a change to the documentation repo, `lookit-docs <https://github.com/lookit/lookit-docs>`_. Making a "pull request" or PR is a way to ask that your edits be incorporated into the main codebase. It's actually not too hard, and it's a great way to contribute! 
 
-Don't worry about making a mistake and somehow messing up the documentation - you can't directly edit the "official" version of the files! There is always a review process before your changes are merged in. 
+Don't worry about making a mistake and somehow messing up the documentation - you can't directly edit the "official" version of the files! There is always a review process before your changes are merged in. For further instructions on how to create PRs, please see the `GitHub documentation <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.
 
 1. In a separate tab, go to https://github.com/lookit/lookit-docs and click "Fork" in the top right corner. You'll need to make an account on GitHub if you don't have one already. You only need to do this once - for future changes you can skip this step.
 
@@ -36,12 +36,12 @@ Don't worry about making a mistake and somehow messing up the documentation - yo
    .. image:: _static/img/tutorial/new_branch_message.png
       :alt: New branch message on GitHub
 
-4. Make your changes! For this PR, just add your name and institution to the list of tutorial participants. Click the "Preview changes" tab to make sure everything looks the way you want it to. You can go back and forth between the "Edit file" and "Preview changes" tabs as you make more involved changes.
+4. Make your changes! For this PR, just add your name and institution to the list of tutorial participants. Click the "Preview" button to make sure everything looks the way you want it to. You can go back and forth between the "Edit" and "Preview" selections as you make more involved changes.  
 
    .. image:: _static/img/tutorial/preview_tab.png
       :alt: Preview changes and edit file tabs on GitHub
 
-5. Scroll down to "Propose file change." Enter a short description of your change, and then click the green "Propose file change" button:
+5. Once you're satisfied with your changes, click the green button "Commit changes..." and a pop up window will appear.  Enter a short description of your change, and then click the green "Propose changes" button:
 
    .. image:: _static/img/tutorial/propose_file_change.png
       :alt: Propose file change section on GitHub