Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update for expanded manubot package #48

Merged
merged 6 commits into from Aug 9, 2017

Conversation

Projects
None yet
2 participants
@dhimmel
Copy link
Member

dhimmel commented Aug 4, 2017

Update based on the Manubot changes introduced by manubot/manubot#2.

@dhimmel dhimmel requested a review from agitter Aug 8, 2017

@dhimmel dhimmel force-pushed the dhimmel:upgrade branch from 23ee76b to db13945 Aug 8, 2017

@dhimmel dhimmel force-pushed the dhimmel:upgrade branch from db13945 to a0f8980 Aug 8, 2017

@agitter
Copy link
Member

agitter left a comment

The reorganization looks great. The expanded documentation is especially nice.

I found one broken link. The rest of the comments are optional suggestions.


## 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)).

This comment has been minimized.

@agitter

agitter Aug 9, 2017

Member

Fix link for citeproc JSON.

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

This comment has been minimized.

@agitter

agitter Aug 9, 2017

Member

Sentence case is used elsewhere (i.e. Manubot markdown)

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

This comment has been minimized.

@agitter

agitter Aug 9, 2017

Member

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.

This comment has been minimized.

@agitter

agitter Aug 9, 2017

Member

webpage directory and rendered as a webpage


## 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).

This comment has been minimized.

@agitter

agitter Aug 9, 2017

Member

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

This comment has been minimized.

@agitter

agitter Aug 9, 2017

Member

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.

This comment has been minimized.

@agitter

agitter Aug 9, 2017

Member

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.

This comment has been minimized.

@dhimmel

dhimmel Aug 9, 2017

Author Member

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?

This comment has been minimized.

@agitter

agitter Aug 9, 2017

Member

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.

@agitter

agitter approved these changes Aug 9, 2017

@dhimmel dhimmel force-pushed the dhimmel:upgrade branch from 2b0d8f4 to 663aa09 Aug 9, 2017

@dhimmel dhimmel merged commit 084e30d into manubot:master Aug 9, 2017

1 check was pending

continuous-integration/travis-ci/pr The Travis CI build is in progress
Details

@dhimmel dhimmel deleted the dhimmel:upgrade branch Aug 9, 2017

dhimmel added a commit that referenced this pull request Aug 9, 2017

Update for expanded manubot package (#48)
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

dhimmel added a commit that referenced this pull request Aug 9, 2017

Update for expanded manubot package (#48)
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.