diff --git a/docs/conf.py b/docs/conf.py index a7623702..b3d86918 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/editing.md b/docs/editing.md index 1cea4278..8073e219 100644 --- a/docs/editing.md +++ b/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 `_. +```{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 `_ 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. diff --git a/docs/editorial_bot.md b/docs/editorial_bot.md index b21b4110..550cbb19 100644 --- a/docs/editorial_bot.md +++ b/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 `_. +```{note} +To compile the papers ``@editorialbot`` is running this `Docker image `_. ``` 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 diff --git a/docs/installing.md b/docs/installing.md index 48297679..0ad9e710 100644 --- a/docs/installing.md +++ b/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 `_ 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, diff --git a/docs/policies.md b/docs/policies.md index eb87fb3c..eef40b50 100644 --- a/docs/policies.md +++ b/docs/policies.md @@ -1,5 +1,4 @@ -JOSS Policies -========================== +# JOSS Policies ## Animal research policy diff --git a/docs/requirements.txt b/docs/requirements.txt index 2fd25f6d..c935b13a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,3 @@ docutils -recommonmark sphinx_rtd_theme +myst-parser diff --git a/docs/review_checklist.md b/docs/review_checklist.md index 5b24bb25..d6c114a6 100644 --- a/docs/review_checklist.md +++ b/docs/review_checklist.md @@ -1,34 +1,34 @@ -Review checklist -================ +# Review checklist JOSS reviews are checklist-driven. That is, there is a checklist for each JOSS reviewer to work through when completing their review. A JOSS review is generally considered incomplete until the reviewer has checked off all of their checkboxes. Below is an example of the review checklist for the [Yellowbrick JOSS submission](https://github.com/openjournals/joss-reviews/issues/1075). -```eval_rst -.. important:: Note this section of our documentation only describes the JOSS review checklist. Authors and reviewers should consult the `review criteria `_ to better understand how these checklist items should be interpreted. + +```{important} +Note this section of our documentation only describes the JOSS review checklist. Authors and reviewers should consult the [review criteria](review_criteria) to better understand how these checklist items should be interpreted. ``` -### Conflict of interest +## Conflict of interest -- I confirm that I have read the [JOSS conflict of interest policy](reviewer_guidelines.html#joss-conflict-of-interest-policy) and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review. +- I confirm that I have read the [JOSS conflict of interest policy](reviewer_guidelines.md#joss-conflict-of-interest-policy) and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review. -### Code of Conduct +## Code of Conduct - I confirm that I read and will adhere to the [JOSS code of conduct](https://joss.theoj.org/about#code_of_conduct). -### General checks +## General checks - **Repository:** Is the source code for this software available at the repository url? - **License:** Does the repository contain a plain-text LICENSE file with the contents of an [OSI approved](https://opensource.org/licenses/alphabetical) software license? - **Contribution and authorship:** Has the submitting author made major contributions to the software? Does the full list of paper authors seem appropriate and complete? -### Functionality +## Functionality - **Installation:** Does installation proceed as outlined in the documentation? - **Functionality:** Have the functional claims of the software been confirmed? - **Performance:** If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.) -### Documentation +## Documentation - **A statement of need:** Do the authors clearly state what problems the software is designed to solve and who the target audience is? - **Installation instructions:** Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution. @@ -37,7 +37,7 @@ Below is an example of the review checklist for the [Yellowbrick JOSS submission - **Automated tests:** Are there automated tests or manual steps described so that the functionality of the software can be verified? - **Community guidelines:** Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support -### Software paper +## Software paper - **Summary:** Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided? - **A statement of need:** Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work? diff --git a/docs/review_criteria.md b/docs/review_criteria.md index 3bd3d2d0..a8c3ab32 100644 --- a/docs/review_criteria.md +++ b/docs/review_criteria.md @@ -1,9 +1,8 @@ -Review criteria -=============== +# Review criteria ## The JOSS paper -As outlined in the [submission guidelines provided to authors](submitting.html#what-should-my-paper-contain), the JOSS paper (the compiled PDF associated with this submission) should only include: +As outlined in the [submission guidelines provided to authors](submitting.md#what-should-my-paper-contain), the JOSS paper (the compiled PDF associated with this submission) should only include: - A list of the authors of the software and their affiliations. - A summary describing the high-level functionality and purpose of the software for a diverse, non-specialist audience. @@ -12,14 +11,14 @@ As outlined in the [submission guidelines provided to authors](submitting.html#w - Mentions (if applicable) of any ongoing research projects using the software or recent scholarly publications enabled by it. - A list of key references including a link to the software archive. -```eval_rst -.. important:: Note the paper *should not* include software documentation such as API (Application Programming Interface) functionality, as this should be outlined in the software documentation. +```{important} +Note the paper *should not* include software documentation such as API (Application Programming Interface) functionality, as this should be outlined in the software documentation. ``` ## Review items -```eval_rst -.. important:: Note, if you've not yet been involved in a JOSS review, you can see an example JOSS review checklist `here `_. +```{important} +Note, if you've not yet been involved in a JOSS review, you can see an example JOSS review checklist [here](review_checklist). ``` ### Software license @@ -42,8 +41,8 @@ Reviewers should verify that the software represents substantial scholarly effor These guidelines are not meant to be strictly prescriptive. Recently released software may not have been around long enough to gather citations in academic literature. While some authors contribute openly and accrue a long and rich commit history before submitting, others may upload their software to GitHub shortly before submitting their JOSS paper. Reviewers should rely on their expert understanding of their domain to judge whether the software is of broad interest (_likely to be cited by other researchers_) or more narrowly focused around the needs of an individual researcher or lab. -```eval_rst -.. note:: The decision on scholarly effort is ultimately one made by JOSS editors. Reviewers are asked to flag submissions of questionable scope during the review process so that the editor can bring this to the attention of the JOSS editorial team. +```{note} +The decision on scholarly effort is ultimately one made by JOSS editors. Reviewers are asked to flag submissions of questionable scope during the review process so that the editor can bring this to the attention of the JOSS editorial team. ``` ### Documentation @@ -74,8 +73,8 @@ Reviewers should check that the software API is documented to a suitable level. > **OK:** Core API functionality is documented
> **Bad (not acceptable):** API is undocumented -```eval_rst -.. note:: The decision on API documentation is left largely to the discretion of the reviewer and their experience of evaluating the software. +```{note} +The decision on API documentation is left largely to the discretion of the reviewer and their experience of evaluating the software. ``` #### Community guidelines @@ -104,7 +103,7 @@ Authors are strongly encouraged to include an automated test suite covering the As part of the review process, you are asked to check whether the submitting author has made a 'substantial contribution' to the submitted software (as determined by the commit history) and to check that 'the full list of paper authors seems appropriate and complete?' -As discussed in the [submission guidelines for authors](submitting.html#authorship), authorship is a complex topic with different practices in different communities. Ultimately, the authors themselves are responsible for deciding which contributions are sufficient for co-authorship, although JOSS policy is that purely financial contributions are not considered sufficient. Your job as a reviewer is to check that the list of authors appears reasonable, and if it's not obviously complete/correct, to raise this as a question during the review. +As discussed in the [submission guidelines for authors](submitting.md#authorship), authorship is a complex topic with different practices in different communities. Ultimately, the authors themselves are responsible for deciding which contributions are sufficient for co-authorship, although JOSS policy is that purely financial contributions are not considered sufficient. Your job as a reviewer is to check that the list of authors appears reasonable, and if it's not obviously complete/correct, to raise this as a question during the review. ### An important note about 'novel' software and citations of relevant work diff --git a/docs/reviewer_guidelines.md b/docs/reviewer_guidelines.md index d20b57eb..32cf4cc1 100644 --- a/docs/reviewer_guidelines.md +++ b/docs/reviewer_guidelines.md @@ -1,5 +1,4 @@ -Reviewing for JOSS -======================= +# Reviewing for JOSS Firstly, thank you so much for agreeing to review for the Journal of Open Source Software (JOSS), we're delighted to have your help. This document is designed to outline our editorial guidelines and help you understand our requirements for accepting a submission into the JOSS. Our review process is based on a tried-and-tested approach of the [rOpenSci collaboration](http://ropensci.org/blog/2016/03/28/software-review). diff --git a/docs/submitting.md b/docs/submitting.md index 357d2687..e1eeeb44 100644 --- a/docs/submitting.md +++ b/docs/submitting.md @@ -1,5 +1,4 @@ -Submitting a paper to JOSS -========================== +# Submitting a paper to JOSS If you've already developed a fully featured research code, released it under an [OSI-approved license](https://opensource.org/licenses), and written good documentation and tests, then we expect that it should take perhaps an hour or two to prepare and submit your paper to JOSS. But please read these instructions carefully for a streamlined submission. @@ -81,8 +80,8 @@ Before you submit, you should: ## What should my paper contain? -```eval_rst -.. important:: Begin your paper with a summary of the high-level functionality of your software for a non-specialist reader. Avoid jargon in this section. +```{important} +Begin your paper with a summary of the high-level functionality of your software for a non-specialist reader. Avoid jargon in this section. ``` JOSS welcomes submissions from broadly diverse research areas. For this reason, we require that authors include in the paper some sentences that explain the software functionality and domain of use to a non-specialist reader. We also require that authors explain the research applications of the software. The paper should be between 250-1000 words. Authors submitting papers significantly longer than 1000 words may be asked to reduce the length of their paper. @@ -98,8 +97,8 @@ Your paper should include: As this short list shows, JOSS papers are only expected to contain a limited set of metadata (see example below), a Statement of need, Summary, Acknowledgements, and References sections. You can look at an [example accepted paper](#example-paper-and-bibliography). Given this format, a "full length" paper is not permitted, and software documentation such as API (Application Programming Interface) functionality should not be in the paper and instead should be outlined in the software documentation. -```eval_rst -.. important:: Your paper will be reviewed by two or more reviewers in a public GitHub issue. Take a look at the `review checklist `_ and `review criteria `_ to better understand how your submission will be reviewed. +```{important} +Your paper will be reviewed by two or more reviewers in a public GitHub issue. Take a look at the [review checklist](review_checklist) and [review criteria](review_criteria) to better understand how your submission will be reviewed. ``` ## How should my paper be formatted? @@ -108,6 +107,7 @@ Submitted articles must use Markdown and must provide a metadata section at the ### Article metadata +(author-names)= #### Names Providing an author name is straight-forward: just set the `name` attribute. However, sometimes more control over the name is required. @@ -327,9 +327,8 @@ Mark equations and other math content with dollar signs ($). Use a single dollar To give some examples: When discussing a variable *x* or a short formula like -```eval_rst -.. math:: - \sin \frac{\pi}{2} +```{math} +\sin \frac{\pi}{2} ``` we would write $x$ and @@ -357,7 +356,7 @@ Software should use an OSI-approved license. The above example results in the following output: -> ```eval_rst +> ```{eval-rst} > > Articles are published under a Creative Commons license [#f1]_. Software should use an OSI-approved license. > @@ -429,9 +428,9 @@ Rendered: This example `paper.md` is adapted from _Gala: A Python package for galactic dynamics_ by Adrian M. Price-Whelan [http://doi.org/10.21105/joss.00388](http://doi.org/10.21105/joss.00388). -For a complete description of available options to describe author names [see here](#names). +For a complete description of available options to describe author names [see here](author-names). -``` +```markdown --- title: 'Gala: A Python package for galactic dynamics' tags: