Update for expanded manubot package #48
Conversation
CONTRIBUTING.md
Outdated
|
|
||
| ## Reference metadata | ||
|
|
||
| The Manubot workflow requires the bibliographic details for references (the set of all cited works) as CSL (Citation Style Language) Items (also known as citeproc JSON](http://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html#csl-json-items)). |
CONTRIBUTING.md
Outdated
| Check out the [CommonMark Help](http://commonmark.org/help/) page for an introduction to formatting options provided by markdown. | ||
| In addition, to standard markdown features, we support [markdown tables](https://help.github.com/articles/organizing-information-with-tables/ "GitHub Help: Organizing information with tables") and a custom citation syntax. | ||
| Check out [Tables Generator](http://www.tablesgenerator.com/markdown_tables) for creating markdown tables. | ||
| ## Manubot Markdown |
There was a problem hiding this comment.
Sentence case is used elsewhere (i.e. Manubot markdown)
CONTRIBUTING.md
Outdated
| Additional metadata, such as `date`, will automatically be created by the Manubot. | ||
| We recommend authors add themselves to `metadata.yaml` via pull request (when requested by a maintainer), thereby signaling that they've read and approved the manuscript. | ||
|
|
||
| ## Manubot Feedback |
README.md
Outdated
| + [`content`](content) contains the manuscript source, which includes markdown files as well as inputs for citations and references. | ||
| + [`output`](output) contains the outputs (generated files) from the manubot including the resulting manuscripts. | ||
| You should not edit these files manually, because they will get overwritten. | ||
| + [`webapp`](webapp) is a directory meant to be rendered a webpage for viewing the HTML manuscript. |
There was a problem hiding this comment.
webpage directory and rendered as a webpage
CONTRIBUTING.md
Outdated
|
|
||
| ## Manuscript metadata | ||
|
|
||
| [`content/metadata.yaml`](content/metadata.yaml) contains manuscript metadata that gets passed through to Pandoc, via a [`yaml_metadata_block`](http://pandoc.org/MANUAL.html#extension-yaml_metadata_block). |
There was a problem hiding this comment.
We could state here what author information is required and what is optional.
README.md
Outdated
| You can build the manuscript locally on POSIX systems by running the following commands. | ||
|
|
||
| ```sh | ||
| # Activate the manubot conda environment |
There was a problem hiding this comment.
Should this link or refer to the build directory to explain what the manubot environment is?
README.md
Outdated
|
|
||
| The manuscript source is located in [`content`](content). | ||
| Text should be written in markdown files, with a digit prefix for ordering (e.g. `01.`, `02.`, etc.) and a `.md` suffix. | ||
| See [`CONTRIBUTING.md`](CONTRIBUTING.md) for documentation on how to create or contribute to a manuscript. |
There was a problem hiding this comment.
We could split CONTRIBUTING.md so that CONTRIBUTING.md contains only the Manubot feedback section and a new USAGE.md (or similar) contains all of the documentation.
There was a problem hiding this comment.
I think fewer files the better.
USAGE.md is more accurate than CONTRIBUTING.md. Note that GitHub has integration with CONTRIBUTING files. Whenever a user opens a new issue or PR, they will see the link the contributing docs.
Is this good or bad? Perhaps it's a bit misleading to label usage guidelines and contributing guidelines?
There was a problem hiding this comment.
USAGE.md seems to fit the contents better, but the GitHub integration is nice. I was imagining that a cloned manuscript may want one guide describing what type of contributions are welcome, what authorship criteria are being used, etc. and a separate document with instructions. In deep review we ended up putting that information in the readme instead of CONTRIBUTING.md though.
I don't have a strong opinion so go with whatever you feel is best.
This build is based on 084e30d. This commit was created by the following Travis CI build and job: https://travis-ci.org/greenelab/manubot-rootstock/builds/262705136 https://travis-ci.org/greenelab/manubot-rootstock/jobs/262705137 [ci skip] The full commit message that triggered this build is copied below: Update for expanded manubot package (#48) * Update for expanded manubot package * Create distinct caching directory * Deployment: references branch now output * Rewrite documentation * Rename CONTRIBUTING.md to USAGE.md Refs manubot/manubot#2
This build is based on 084e30d. This commit was created by the following Travis CI build and job: https://travis-ci.org/greenelab/manubot-rootstock/builds/262705136 https://travis-ci.org/greenelab/manubot-rootstock/jobs/262705137 [ci skip] The full commit message that triggered this build is copied below: Update for expanded manubot package (#48) * Update for expanded manubot package * Create distinct caching directory * Deployment: references branch now output * Rewrite documentation * Rename CONTRIBUTING.md to USAGE.md Refs manubot/manubot#2
Update based on the Manubot changes introduced by manubot/manubot#2.