Merge pull request #1321 from sneakers-the-rat/myst

Switch `recommonmark` to `myst`

docs/conf.py

@@ -15,8 +15,6 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
-import recommonmark
-from recommonmark.transform import AutoStructify
 
 # -- Project information -----------------------------------------------------
 
@@ -38,7 +36,7 @@
 # ones.
 extensions = [
     'sphinx.ext.mathjax',
-    'recommonmark',
+    'myst_parser',
     'sphinx_rtd_theme',
 ]
 
@@ -126,11 +124,4 @@
 
 
 # -- Extension configuration -------------------------------------------------
-def setup(app):
-    app.add_config_value('recommonmark_config', {
-            'url_resolver': lambda url: github_doc_root + url,
-            'auto_toc_tree_section': 'Contents',
-            'enable_auto_toc_tree': True,
-            'enable_eval_rst': True,
-            }, True)
-    app.add_transform(AutoStructify)
+myst_heading_anchors=3

docs/editing.md

@@ -1,28 +1,27 @@
-Editorial Guide
-===============
+# Editorial Guide
 
 The Journal of Open Source Software (JOSS) conducts all peer review and editorial processes in the open, on the GitHub issue tracker.
 
 JOSS editors manage the review workflow with the help of our bot, `@editorialbot`. The bot is summoned with commands typed directly on the GitHub review issues. For a list of commands, type: `@editorialbot commands`.
 
-```eval_rst
-.. note:: To learn more about ``@editorialbot``'s functionalities, take a look at our `dedicated guide <editorial_bot.html>`_.
+```{note}
+To learn more about `@editorialbot`'s functionalities, take a look at our [dedicated guide](editorial_bot).
 ```
 
 ## Pre-review
 
 Once a submission comes in, it will be in the queue for a quick check by the Track Editor-in-chief (TEiC). From there, it moves to a `PRE-REVIEW` issue, where the TEiC will assign a handling editor, and the author can suggest reviewers. Initial direction to the authors for improving the paper can already happen here, especially if the paper lacks some requested sections.
 
-```eval_rst
-.. important:: If the paper is out-of-scope for JOSS, editors assess this and notify the author in the ``PRE-REVIEW`` issue.
+```{important}
+If the paper is out-of-scope for JOSS, editors assess this and notify the author in the ``PRE-REVIEW`` issue.
 ```
 
 Editors can flag submissions of questionable scope using the command `@editorialbot query scope`.
 
 The TEiC assigns an editor (or a volunteering editor self-assigns) with the command `@editorialbot assign @username as editor` in a comment.
 
-```eval_rst
-.. note:: Please check in on the `dashboard <https://joss.theoj.org/dashboard/incoming>`_ semi-regularly to see which papers are currently without an editor, and if possible, volunteer to edit papers that look to be in your domain. If you choose to be an editor in the issue thread type the command ``@editorialbot assign @yourhandle as editor`` or simply ``@editorialbot assign me as editor``
+```{note}
+Please check in on the [dashboard](https://joss.theoj.org/dashboard/incoming) semi-regularly to see which papers are currently without an editor, and if possible, volunteer to edit papers that look to be in your domain. If you choose to be an editor in the issue thread type the command `@editorialbot assign @yourhandle as editor` or simply `@editorialbot assign me as editor`
 ```
 
 ### How papers are assigned to editors
@@ -123,7 +122,7 @@ JOSS is collaborating with [AAS publishing](https://journals.aas.org/) to offer
 **After the paper has been accepted by JOSS**
 
 - Once the JOSS review is complete, ask the author for the status of their AAS publication, specifically if they have the AAS paper DOI yet.
-- Once this is available, ask the author to add this information to their `paper.md` YAML header as documented in the [submission guidelines](submitting.html#what-should-my-paper-contain).
+- Once this is available, ask the author to add this information to their `paper.md` YAML header as documented in the [submission guidelines](submitting.md#what-should-my-paper-contain).
 
 ```
 # Optional fields if submitting to a AAS journal too, see this blog post:
@@ -168,8 +167,8 @@ In the event that an author re-submits a paper to JOSS that was previously rejec
 
 Once per week, an email is sent to all JOSS editors with a summary of the papers that are currently flagged as potentially out of scope. Editors are asked to review these submissions and vote on the JOSS website if they have an opinion about a submission.
 
-```eval_rst
-.. important:: Your input (vote) on submissions that are undergoing a scope review is incredibly valuable to the EiC team. Please try and vote early, and often!
+```{important}
+Your input (vote) on submissions that are undergoing a scope review is incredibly valuable to the EiC team. Please try and vote early, and often!
 ```
 
 ## Sample messages for authors and reviewers
@@ -340,7 +339,7 @@ Our goal is for editors to handle between 3-4 submissions at any one time, and 8
 JOSS has a 90-day trial period for new editors. At the end of the trial, the editor or JOSS editorial board can decide to part ways if either party determines editing for JOSS isn't a good fit for the editor. The most important traits the editorial board will be looking for with new editors are:
 
 - Demonstrating professionalism in communications with authors, reviewers, and the wider editorial team.
-- Editorial responsibility, including [keeping up with their assigned submissions](editing.html#continued-attention-to-assigned-submissions).
+- Editorial responsibility, including [keeping up with their assigned submissions](#continued-attention-to-assigned-submissions).
 - Encouraging good social (software community) practices. For example, thanking reviewers and making them feel like they are part of a team working together.
 
 If you're struggling with your editorial work, please let your buddy or an EiC know.
@@ -496,7 +495,7 @@ All new editors at JOSS have an onboarding call with an Editor-in-Chief. You can
 - Explain where you can look for editors (your own professional network, asking the authors for recommendations, the [reviewers application](https://reviewers.joss.theoj.org/), similar papers identified by Editorialbot, )
 - Point out that we have a minimum of two reviewers, but if more than that accept (e.g., 3/4 then take them all – this gives you redundancy if one drops out).
 - Don't invite only one reviewer at a time! If you do this, it may take many weeks to find two reviewers who accept. Try 3/4/5 invites simultaneously.
-- The [sample messages](editing.html#sample-messages-for-authors-and-reviewers) section of the documentation has some example language you can use.
+- The [sample messages](#sample-messages-for-authors-and-reviewers) section of the documentation has some example language you can use.
 
 **The review**
 
@@ -505,14 +504,14 @@ All new editors at JOSS have an onboarding call with an Editor-in-Chief. You can
 - Make sure to check in on the review – if reviewers haven't started after ~1-2 weeks, time to remind them.
 - Your role as editor is not to do the review yourself, rather, your job is to ensure that both reviewers give a good review and to facilitate discussion and consensus on what the author needs to do.
 - Walk the editor through the various review artifacts: The checklist, comments/questions/discussion between reviewers and author, issues opened on the upstream repository (and cross-linked into the review thread). 
-- Point editors to the ['top tips'](editing.html#top-tips-for-joss-editors) section of our docs. Much of what makes an editor successful is regular check-ins on the review, and nudging people if nothing is happening.
+- Point editors to the ['top tips'](#top-tips-for-joss-editors) section of our docs. Much of what makes an editor successful is regular check-ins on the review, and nudging people if nothing is happening.
 - Do *not* let a review go multiple weeks without checking in.
 
 **Wrapping up the review**
 
 - Once the review is wrapping up, show the candidate the checks that an editor should be doing (reading the paper, suggested edits, asking for an archive etc.)
 - Show the `recommend-accept` step which is the formal hand-off between editor and editor-in-chief.
-- The [sample messages](editing.html#sample-messages-for-authors-and-reviewers) section of the documentation has a checklist for the last steps of the review (for both authors and editors).
+- The [sample messages](#sample-messages-for-authors-and-reviewers) section of the documentation has a checklist for the last steps of the review (for both authors and editors).
 
 
 **Show them the dashboard on the JOSS site**
@@ -532,7 +531,7 @@ All new editors at JOSS have an onboarding call with an Editor-in-Chief. You can
 
 **Wrapping up**
 
-- Make sure you've highlighted everything in the ['top tips'](editing.html#top-tips-for-joss-editors) section of our docs.
+- Make sure you've highlighted everything in the ['top tips'](#top-tips-for-joss-editors) section of our docs.
 - Reinforce that this is a commitment, and thay regular attention to their submissions is absolutely critical (i.e., check in a couple of times per week).
 - Ask if they would like to move forward or would like time to consider the opportunity.
 - If they want to move forward, highlight they will receive a small number of invites: One to the JOSS editors GitHub team, a Slack invite, a Google Group invite, and an invite to the JOSS website to fill out their profile.

docs/editorial_bot.md

@@ -1,5 +1,4 @@
-Interacting with EditorialBot
-=============================
+# Interacting with EditorialBot
 
 The Open Journals' editorial bot or `@editorialbot` on GitHub, is our editorial bot that interacts with authors, reviewers, and editors on JOSS reviews.
 
@@ -10,8 +9,8 @@ The Open Journals' editorial bot or `@editorialbot` on GitHub, is our editorial
 @editorialbot commands
 ```
 
-```eval_rst
-.. note:: EditorialBot commands must be placed in the first line of a comment. Other text can be added after the first line with the command. Multiple commands are not allowed in the same comment, only the first one will be interpreted.
+```{note}
+EditorialBot commands must be placed in the first line of a comment. Other text can be added after the first line with the command. Multiple commands are not allowed in the same comment, only the first one will be interpreted.
 ```
 
 ## Author and reviewers commands
@@ -24,8 +23,8 @@ When a `pre-review` or `review` issue is opened, `@editorialbot` will try to com
 
 If it can't find the `paper.md` file it will say as much in the review issue. If it can't compile the paper (i.e. there's some kind of Pandoc error), it will try and report that error back in the thread too.
 
-```eval_rst
-.. note:: To compile the papers ``@editorialbot`` is running this `Docker image <https://github.com/openjournals/inara>`_.
+```{note}
+To compile the papers ``@editorialbot`` is running this `Docker image <https://github.com/openjournals/inara>`_.
 ```
 
 Anyone can ask `@editorialbot` to compile the paper again (e.g. after a change has been made). To do this simply comment on the review thread as follows:
@@ -116,8 +115,8 @@ Once the reviewer(s) and editor have been assigned in the `pre-review` issue, th
 @editorialbot start review
 ```
 
-```eval_rst
-.. important:: If a reviewer recants their commitment or is unresponsive, editors can remove them with the command ``@editorialbot remove @username from reviewers``. You can then delete that reviewer's checklist. You can also add new reviewers in the ``REVIEW`` issue with the command ``@editorialbot add @username to reviewers``.
+```{important}
+If a reviewer recants their commitment or is unresponsive, editors can remove them with the command `@editorialbot remove @username from reviewers`. You can then delete that reviewer's checklist. You can also add new reviewers in the `REVIEW` issue with the command `@editorialbot add @username to reviewers`.
 ```
 
 ### Reminding reviewers and authors
@@ -139,8 +138,8 @@ EditorialBot can remind authors and reviewers after a specified amount of time t
 @editorialbot remind @author in two weeks
 ```
 
-```eval_rst
-.. note:: Most units of times are understood by EditorialBot e.g. `hour/hours/day/days/week/weeks`.
+```{note}
+Most units of times are understood by EditorialBot e.g. `hour/hours/day/days/week/weeks`.
 ```
 
 ### Setting the software archive
@@ -184,8 +183,8 @@ Editors can ask EditorialBot to check if the DOIs in the bib file are valid with
 @editorialbot check references
 ```
 
-```eval_rst
-.. note:: EditorialBot can verify that DOIs resolve, but cannot verify that the DOI associated with a paper is actually correct. In addition, DOI suggestions from EditorialBot are just that - i.e. they may not be correct.
+```{note}
+EditorialBot can verify that DOIs resolve, but cannot verify that the DOI associated with a paper is actually correct. In addition, DOI suggestions from EditorialBot are just that - i.e. they may not be correct.
 ```
 
 ### Repository checks

docs/installing.md

@@ -1,5 +1,4 @@
-Installing the JOSS application
-===============================
+# Installing the JOSS application
 
 Any Open Journal (JOSS, JOSE, etc.) can be considered in three parts:
 
@@ -36,18 +35,17 @@ before deploying your application to Heroku:
 1. A GitHub [Personal Access Token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) for the automated account that users will interact with (e.g., `@editorialbot`, `@RoboNeuro`). In order to be able to send invitations to reviewers and collaborators, the automated GitHub account must be an admin of the organization the reviews take place at. And the Personal Access Token should include the `admin:org` scope.
 1. An email address registered on a domain you control (i.e., not `gmail` or a related service)
 
-```eval_rst
-.. warning::
-    Do not put these secrets directly into your code base!
-    It is important that these keys are not under version control.
+```{warning}
+Do not put these secrets directly into your code base!
+It is important that these keys are not under version control.
 
-    There are different ways to make sure your application has access to these keys,
-    depending on whether your code is being developed locally or on Heroku.
-    Locally, you can store these locally in a .env file.
-    The .gitignore in JOSS is already set to ignore this file type.
+There are different ways to make sure your application has access to these keys,
+depending on whether your code is being developed locally or on Heroku.
+Locally, you can store these locally in a .env file.
+The .gitignore in JOSS is already set to ignore this file type.
 
-    On Heroku, they will be config variables that you can set either with the Heroku CLI or directly on your application's dashboard.
-    See `this guide from Heroku <https://devcenter.heroku.com/articles/config-vars#managing-config-vars>`_ for more information.
+On Heroku, they will be config variables that you can set either with the Heroku CLI or directly on your application's dashboard.
+See [this guide from Heroku](https://devcenter.heroku.com/articles/config-vars#managing-config-vars) for more information.
 ```
 
 Assuming you [have forked the JOSS GitHub repository](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo)
@@ -75,24 +73,22 @@ Once you've pushed your application to Heroku and provisioned the appropriate ad
 you're ready to update your config with the appropriate secrets.
 For a list of the expected secret key names, see the `app.json` file.
 
-```eval_rst
-.. warning::
-    One "gotcha" when provisioning the Bonsai add-on is that it may only set the BONSAI_URL variable.
-    Make sure that there is also an ELASTICSEARCH_URL which is set to the same address.
+```{warning}
+One "gotcha" when provisioning the Bonsai add-on is that it may only set the `BONSAI_URL` variable.
+Make sure that there is also an `ELASTICSEARCH_URL` which is set to the same address.
 ```
 
 We will not cover Portico, as this requires that your application is a part of the `openjournals` organization.
 If you do not already have access to these keys, you can simply ignore them for now.
 
-```eval_rst
-.. note::
-    One secret key we have not covered thus far is BOT_SECRET.
-    This is because it is not one that you obtain from a provide,
-    but a secret key that you set yourself.
-    We recommend using something like a random SHA1 string.
+```{note}
+One secret key we have not covered thus far is `BOT_SECRET`.
+This is because it is not one that you obtain from a provide,
+but a secret key that you set yourself.
+We recommend using something like a random SHA1 string.
 
-    It is important to remember this key,
-    as you will need it when deploying your Buffy application.
+It is important to remember this key,
+as you will need it when deploying your Buffy application.
 ```
 
 After pushing your application to Heroku, provisioning the appropriate add-ons,

docs/policies.md

@@ -1,5 +1,4 @@
-JOSS Policies
-==========================
+# JOSS Policies
 
 ## Animal research policy
 

docs/requirements.txt

@@ -1,3 +1,3 @@
 docutils
-recommonmark
 sphinx_rtd_theme
+myst-parser