diff --git a/.appveyor.yml b/.appveyor.yml index 962f2f7e..3e79976c 100644 --- a/.appveyor.yml +++ b/.appveyor.yml @@ -8,10 +8,11 @@ skip_branch_with_pr: true # to only build commits from pull requests branches: only: + - main - master # Only run AppVeyor on commits that modify at least one of the following files -# Delete these lines to run AppVeyor on all master branch commits +# Delete these lines to run AppVeyor on all main/master branch commits only_commits: files: - .appveyor.yml diff --git a/.github/workflows/manubot.yaml b/.github/workflows/manubot.yaml index ad074547..a0c9ccbd 100644 --- a/.github/workflows/manubot.yaml +++ b/.github/workflows/manubot.yaml @@ -2,50 +2,89 @@ name: Manubot on: push: branches: + - main - master pull_request: branches: + - main - master + # NOTE: scheduled workflows aren't supported + # https://github.community/t/github-event-repository-fork-context-does-detect-forks-in-scheduled-jobs/185925 + workflow_dispatch: + inputs: + BUILD_PDF: + type: boolean + description: generate PDF output + default: true + BUILD_DOCX: + type: boolean + description: generate DOCX output + default: true + BUILD_LATEX: + type: boolean + description: generate LaTeX output + default: false + SPELLCHECK: + type: boolean + description: Check spelling + default: true + MANUBOT_USE_DOCKER: + type: boolean + description: Use Docker to generate PDF + default: true jobs: manubot: name: Manubot runs-on: ubuntu-latest env: GITHUB_PULL_REQUEST_SHA: ${{ github.event.pull_request.head.sha }} + # Set SPELLCHECK to true/false for whether to check spelling in this action. + # For workflow dispatch jobs, this SPELLCHECK setting will be overridden by the user input. SPELLCHECK: true + defaults: + run: + shell: bash --login {0} steps: - - name: Set Environment Variables - run: | - TRIGGERING_SHA=${GITHUB_PULL_REQUEST_SHA:-$GITHUB_SHA} - echo "TRIGGERING_SHA_7=${TRIGGERING_SHA::7}" >> $GITHUB_ENV - echo "TRIGGERING_SHA: $TRIGGERING_SHA" - name: Checkout Repository uses: actions/checkout@v2 with: # fetch entire commit history to support get_rootstock_commit fetch-depth: 0 + - name: Set Environment Variables (Workflow Dispatch) + if: github.event_name == 'workflow_dispatch' + run: | + echo "BUILD_PDF=${{ github.event.inputs.BUILD_PDF }}" >> $GITHUB_ENV + echo "BUILD_DOCX=${{ github.event.inputs.BUILD_DOCX }}" >> $GITHUB_ENV + echo "BUILD_LATEX=${{ github.event.inputs.BUILD_LATEX }}" >> $GITHUB_ENV + echo "SPELLCHECK=${{ github.event.inputs.SPELLCHECK }}" >> $GITHUB_ENV + echo "MANUBOT_USE_DOCKER=${{ github.event.inputs.MANUBOT_USE_DOCKER }}" >> $GITHUB_ENV + - name: Set Environment Variables + run: | + TRIGGERING_SHA=${GITHUB_PULL_REQUEST_SHA:-$GITHUB_SHA} + echo "TRIGGERING_SHA_7=${TRIGGERING_SHA::7}" >> $GITHUB_ENV + echo "TRIGGERING_SHA: $TRIGGERING_SHA" + DEFAULT_BRANCH=${{ github.event.repository.default_branch }} + echo "DEFAULT_BRANCH=${DEFAULT_BRANCH}" >> $GITHUB_ENV + echo "DEFAULT_BRANCH_REF=refs/heads/$DEFAULT_BRANCH" >> $GITHUB_ENV + echo "DEFAULT_BRANCH=$DEFAULT_BRANCH" - name: Cache uses: actions/cache@v1 with: path: ci/cache key: ci-cache-${{ github.ref }} restore-keys: | - ci-cache-refs/heads/master + ci-cache-${{ env.DEFAULT_BRANCH_REF }} - name: Install Environment uses: conda-incubator/setup-miniconda@v2 with: activate-environment: manubot environment-file: build/environment.yml auto-activate-base: false - miniconda-version: 'latest' + miniforge-version: 'latest' - name: Install Spellcheck - shell: bash --login {0} - run: | - if [ "${SPELLCHECK:-}" = "true" ]; then - bash ci/install-spellcheck.sh - fi + if: env.SPELLCHECK == 'true' + run: bash ci/install-spellcheck.sh - name: Build Manuscript - shell: bash --login {0} run: BUILD_DOCX=true bash build/build.sh - name: Upload Artifacts uses: actions/upload-artifact@v1 @@ -53,11 +92,10 @@ jobs: name: manuscript-${{ github.run_id }}-${{ env.TRIGGERING_SHA_7 }} path: output - name: Deploy Manuscript - if: github.ref == 'refs/heads/master' && github.event_name == 'push' && !github.event.repository.fork + if: github.ref == env.DEFAULT_BRANCH_REF && github.event_name != 'pull_request' && !github.event.repository.fork env: MANUBOT_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }} MANUBOT_SSH_PRIVATE_KEY: ${{ secrets.MANUBOT_SSH_PRIVATE_KEY }} CI_BUILD_WEB_URL: https://github.com/${{ github.repository }}/commit/${{ github.sha }}/checks - CI_JOB_WEB_URL: https://github.com/${{ github.repository }}/runs/${{ github.run_id }} - shell: bash --login {0} + CI_JOB_WEB_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }} run: bash ci/deploy.sh diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index a8421383..00000000 --- a/.travis.yml +++ /dev/null @@ -1,24 +0,0 @@ -dist: trusty -sudo: false -language: generic -services: - - docker -branches: - only: - - master -env: - - SPELLCHECK=true -install: - - source ci/install.sh -script: - - bash build/build.sh -cache: - directories: - - ci/cache -deploy: - provider: script - script: bash ci/deploy.sh - skip_cleanup: true - on: - branch: master - condition: $TRAVIS_EVENT_TYPE = "push" && (-v MANUBOT_SSH_PRIVATE_KEY || "${!encrypted_*}" != "") diff --git a/README.md b/README.md index b9211f3d..9ca1a379 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ -[![HTML Manuscript](https://img.shields.io/badge/manuscript-HTML-blue.svg)](https://AlexsLemonade.github.io/OpenPBTA-manuscript/) -[![PDF Manuscript](https://img.shields.io/badge/manuscript-PDF-blue.svg)](https://AlexsLemonade.github.io/OpenPBTA-manuscript/manuscript.pdf) -[![GitHub Actions Status](https://github.com/AlexsLemonade/OpenPBTA-manuscript/workflows/Manubot/badge.svg)](https://github.com/AlexsLemonade/OpenPBTA-manuscript/actions) +[![HTML Manuscript](https://img.shields.io/badge/manuscript-HTML-blue.svg)](https://manubot.github.io/rootstock/) +[![PDF Manuscript](https://img.shields.io/badge/manuscript-PDF-blue.svg)](https://manubot.github.io/rootstock/manuscript.pdf) +[![GitHub Actions Status](https://github.com/manubot/rootstock/workflows/Manubot/badge.svg)](https://github.com/manubot/rootstock/actions) ## Manuscript description @@ -81,13 +81,13 @@ Whenever a pull request is opened, CI (continuous integration) will test whether The build process aims to detect common errors, such as invalid citations. If your pull request build fails, see the CI logs for the cause of failure and revise your pull request accordingly. -When a commit to the `master` branch occurs (for example, when a pull request is merged), CI builds the manuscript and writes the results to the [`gh-pages`](https://github.com/manubot/rootstock/tree/gh-pages) and [`output`](https://github.com/manubot/rootstock/tree/output) branches. +When a commit to the `main` branch occurs (for example, when a pull request is merged), CI builds the manuscript and writes the results to the [`gh-pages`](https://github.com/manubot/rootstock/tree/gh-pages) and [`output`](https://github.com/manubot/rootstock/tree/output) branches. The `gh-pages` branch uses [GitHub Pages](https://pages.github.com/) to host the following URLs: + **HTML manuscript** at https://AlexsLemonade.github.io/OpenPBTA-manuscript/ + **PDF manuscript** at https://AlexsLemonade.github.io/OpenPBTA-manuscript/manuscript.pdf -For continuous integration configuration details, see [`.github/workflows/manubot.yaml`](.github/workflows/manubot.yaml) if using GitHub Actions or [`.travis.yml`](.travis.yml) if using Travis CI. +For continuous integration configuration details, see [`.github/workflows/manubot.yaml`](.github/workflows/manubot.yaml). ## License diff --git a/SETUP.md b/SETUP.md index 136376c1..6e423ca0 100644 --- a/SETUP.md +++ b/SETUP.md @@ -1,18 +1,19 @@ # Table of contents - [Creating a new manuscript](#creating-a-new-manuscript) - * [Configuration](#configuration) + * [Using setup script](#using-setup-script) + * [Manual configuration](#manual-configuration) * [Create repository](#create-repository) * [Continuous integration](#continuous-integration) + [GitHub Actions](#github-actions) + [SSH Deploy Key](#ssh-deploy-key) - [Add the public key to GitHub](#add-the-public-key-to-github) - [Add the private key to GitHub](#add-the-private-key-to-github) - + [Travis CI](#travis-ci) + [Previewing pull request builds with AppVeyor](#previewing-pull-request-builds-with-appveyor) * [README updates](#readme-updates) * [Finalize](#finalize) - [Merging upstream rootstock changes](#merging-upstream-rootstock-changes) + * [Default branch](#default-branch) _generated with [markdown-toc](https://ecotrust-canada.github.io/markdown-toc/)_ @@ -26,8 +27,33 @@ These steps should be performed in a command-line shell (terminal), starting in Setup is supported on Linux, macOS, and Windows. Windows setup requires [Git Bash](https://gitforwindows.org/) or [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/faq). -## Configuration +## Using setup script +Creating a new manuscript using GitHub actions, the recommended default CI service (see below), can be achieved easily using the [setup script](https://github.com/manubot/rootstock/blob/main/setup.bash). +This simply runs the steps detailed below in the manual configuration. +Use the command below to copy `setup.bash` and run it. +You can check the code that will be executed [here](https://github.com/manubot/rootstock/blob/main/setup.bash). + +````sh +bash <( curl --location https://github.com/manubot/rootstock/raw/main/setup.bash ) +```` +The script will then take you through the process of cloning the rootstock repo, make the changes required to use GitHub actions, edit the README to point to your repo and commit the changes. +Your new manuscript repo is then ready for you to start adding your own content. + +This script does not not create the remote repo for you, so you will be prompted to manually create an empty GitHub repository at . +Do not initialize the repository, other than optionally adding a description. + +### CLI +There is also a command line interface for users who want to create manuscripts at scale and in an automated way. +See the help for details. + +````sh +bash setup.bash --help +```` + +## Manual configuration + +If you do not wish to use the above setup script to configure your new manuscript repository, you can instead execute the steps manually. First, you must configure two environment variables (`OWNER` and `REPO`). These variables specify the GitHub repository for the manuscript (i.e. `https://github.com/OWNER/REPO`). Make sure that the case of `OWNER` matches how your username is displayed on GitHub. @@ -62,13 +88,14 @@ git remote set-url origin https://github.com/$OWNER/$REPO.git git remote set-url origin git@github.com:$OWNER/$REPO.git ``` -Next, you must manually create an empty GitHub repository at . +Then create an empty repository on GitHub. +You can do this at or via the [GitHub command line interface](https://github.com/cli/cli) (if installed) with `gh repo create`. Make sure to use the same "Owner" and "Repository name" specified above. Do not initialize the repository, other than optionally adding a Description. Next, push your cloned manuscript: ```sh -git push --set-upstream origin master +git push --set-upstream origin main ``` ## Continuous integration @@ -80,7 +107,6 @@ Manubot supports the following CI services: | Service | Default | Artifacts | Deployment | Config | Private Repos | |---------|---------|-----------|---------|--------|---------------| | [GitHub Actions](https://github.com/features/actions) | ✔️ | ✔️ | ✔️ | [`manubot.yaml`](.github/workflows/manubot.yaml) | 2,000 minutes per month | -| [Travis CI](https://travis-ci.com) | ❌ | ❌ | ✔️ needs setup | [`.travis.yml`](.travis.yml) | 100 build trial | | [AppVeyor](https://www.appveyor.com/) | ❌ | ✔️ with PR comments | ❌ | [`.appveyor.yml`](.appveyor.yml) | 14 day trial | Notes on table fields: @@ -93,25 +119,25 @@ Notes on table fields: - **Deployment**: Whether the CI service can write outputs back to the GitHub repository (to the `output` and `gh-pages` branches). Deployment provides GitHub Pages with the latest manuscript version to serve to the manuscript's URL. GitHub Actions will deploy by default without any additional setup. - Travis CI will only deploy if an SSH Private Key is provided. - To avoid deploying a manuscript multiple times, disable GitHub Actions before providing an SSH Private Key to Travis. - **Config**: File configuring what operations CI will perform. Removing this file is one method to disable the CI service. - **Private Repos**: Quota for private repos. Only GitHub Actions supports cost-free builds of private repositories beyond a trial period. All services are cost-free for public repos. +Manubot was originally designed to use Travis CI, +but later switched to primarily use GitHub Actions. +Support for Travis was [removed](https://github.com/manubot/rootstock/issues/446) in 2021. + ### GitHub Actions GitHub Actions is the recommended default CI service because it requires no additional setup. To use GitHub Actions only, remove configuration files for other CI services: ```shell -# remove Travis CI config -git rm .travis.yml # remove AppVeyor config git rm .appveyor.yml -# remove ci/install.sh if using neither Travis CI nor AppVeyor +# remove ci/install.sh (only used by AppVeyor) git rm ci/install.sh ``` @@ -120,9 +146,10 @@ GitHub Pages deployment using `GITHUB_TOKEN` recently started working on GitHub If it does not work for you after completing this setup, try reselecting "gh-pages branch" as the Source for GitHub Pages in the repository Settings. GitHub Pages should now trigger on the next commit. If not, [let us know](https://github.com/manubot/rootstock/issues/new). -For more reliable deployment on GitHub, you can also use an SSH Deploy Key instead (see below). -Deploying on Travis CI requires creating an SSH Deploy Key. +For an alternative deployment method on GitHub, +you can use an SSH Deploy Key instead. +However, the setup is more complex. The following sections, collapsed by default, detail how to generate an SSH Deploy Key.
@@ -130,9 +157,9 @@ The following sections, collapsed by default, detail how to generate an SSH Depl ### SSH Deploy Key -Deployment on Travis CI requires an SSH Deploy Key. -Previously, GitHub Actions also required an SSH Deploy Key, but now GitHub can deploy using the `GITHUB_TOKEN` secret. -Therefore, users following the default configuration of deploying only via GitHub Actions can skip these steps. +Previously, GitHub Actions required an SSH Deploy Key, +but now GitHub can deploy using the `GITHUB_TOKEN` secret. +Therefore, users following the default configuration can skip these steps. Otherwise, generate a deploy key so CI can write to the repository. ```sh @@ -143,7 +170,7 @@ ssh-keygen \ -f ci/deploy.key # Encode deploy.key to remove newlines, writing encoded text to deploy.key.txt. -# This is required for entry into the Travis settings. +# This was required for entry into the Travis settings. openssl base64 -A -in ci/deploy.key > ci/deploy.key.txt ``` @@ -166,7 +193,6 @@ Finally, click "Add key". #### Add the private key to GitHub If you would like GitHub Actions to use SSH for deployment, rather than via HTTPS using `GITHUB_TOKEN`, perform the steps in this section. -**Skip this section if solely using Travis CI for deployment.** ```sh # Print the URL for adding the private key to GitHub @@ -183,43 +209,6 @@ Next, copy-paste the content of `ci/deploy.key.txt` into "Value" (printed above by `cat`, including any trailing `=` characters if present).
-
-Expand for Travis CI setup - -### Travis CI - -Travis CI is another option for continuous integration. -Now you must manually enable Travis CI for the new repository at . -Click the `+` sign to "Add New Repository". -If you don't see your repository listed, push the "Sync account" button. -Finally, flick the repository's switch to enable CI. - -```sh -# Print the URL for adding the private key to Travis CI -echo "https://travis-ci.com/$OWNER/$REPO/settings" - -# Print the encoded private key for copy-pasting to Travis CI -cat ci/deploy.key.txt && echo -``` - -Next, go to the Travis CI repository settings page (URL echoed above). -Add a new record in the "Environment Variables" section. -For "NAME", enter `MANUBOT_SSH_PRIVATE_KEY`. -Next, copy-paste the content of `deploy.key.txt` into "VALUE" -(printed above by `cat`, including any trailing `=` characters if present). -Make sure "Display value in build logs" remains toggled off (the default). - -While in the Travis CI settings, activate the [limit concurrent jobs](https://blog.travis-ci.com/2014-07-18-per-repository-concurrency-setting/) toggle and enter `1` in the value field. -This ensures previous Manubot builds deploy before subsequent ones begin. - -Once the public and private deploy keys have been copied to their cloud locations, you can optionally remove the untracked files: - -```sh -# Optionally remove untracked files -rm ci/deploy.key* -``` - -
Expand for AppVeyor setup @@ -227,7 +216,7 @@ rm ci/deploy.key* ### Previewing pull request builds with AppVeyor You can optionally enable AppVeyor continuous integration to view pull request builds. -Unlike Travis CI, AppVeyor supports storing manuscripts generated during pull request builds as artifacts. +AppVeyor supports storing manuscripts generated during pull request builds as artifacts. These can be previewed to facilitate pull request review and ensure formatting and reference changes render as expected. When a pull request build runs successfully, **@AppVeyorBot** will comment on the pull request with a download link to the manuscript PDF. @@ -263,7 +252,7 @@ If the changes look okay, commit and push: ```shell git add --update git commit --message "Brand repo to $OWNER/$REPO" -git push origin master +git push origin main ``` You should be good to go now. @@ -290,7 +279,7 @@ Second, pull the new commits from rootstock, but do not automerge: git config remote.rootstock.url || git remote add rootstock https://github.com/manubot/rootstock.git # pull the new commits from rootstock -git pull --no-ff --no-rebase --no-commit rootstock master +git pull --no-ff --no-rebase --no-commit rootstock main ``` If all goes well, there won't be any conflicts. @@ -302,7 +291,7 @@ You may notice changes that affect how items in `content` are processed. If so, you should edit and stage `content` files as needed. When there are no longer any unstaged changes, then do `git commit`. -If updating `master` via a pull request, proceed to push the commit to GitHub and open a pull request. +If updating your default branch (i.e. `main` or `master`) via a pull request, proceed to push the commit to GitHub and open a pull request. Once the pull request is ready to merge, use GitHub's "Create a merge commit" option rather than "Squash and merge" or "Rebase and merge" to preserve the rootstock commit hashes. The environment for local builds does not automatically update when [`build/environment.yml`](build/environment.yml) changes. @@ -312,3 +301,18 @@ To update your local conda `manubot` environment with new changes, run: # update a local conda environment conda env update --file build/environment.yml ``` + +## Default branch + +On 2020-10-01, GitHub [changed](https://github.blog/changelog/2020-10-01-the-default-branch-for-newly-created-repositories-is-now-main/) the default branch name for new repositories from `master` to `main`. +More information on GitHub's migration is available at [github/renaming](https://github.com/github/renaming). + +On 2020-12-10, Manubot [updated](https://github.com/manubot/rootstock/pull/399) the Rootstock default branch to `main`. +For existing manuscripts, the default branch will remain `master`, +unless manually switched to `main`. +Rootstock has been configured to run continuous integration on both `main` and `master`, +so existing manuscripts can, but are not required, to switch their default branch to `main`. + +Upgrading to the latest Rootstock will change several READMEs links to `main`. +For manuscripts that do not plan to switch their default branch, +do not include these changes in the upgrade merge commit. diff --git a/USAGE.md b/USAGE.md index 43230773..6add1dc9 100644 --- a/USAGE.md +++ b/USAGE.md @@ -13,7 +13,7 @@ For basic formatting, check out the [CommonMark Help](https://commonmark.org/hel In addition, Manubot supports an extended version of markdown, tailored for scholarly writing, which includes [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) and the extensions discussed below. The `content/02.delete-me.md` file in the Rootstock repository shows many of the elements and formatting options supported by Manubot. -See the [raw markdown](https://gitlab.com/manubot/rootstock/blob/master/content/02.delete-me.md#L) in this file and compare it to the [rendered manuscript](https://manubot.github.io/rootstock/). +See the [raw markdown](https://gitlab.com/manubot/rootstock/blob/main/content/02.delete-me.md#L) in this file and compare it to the [rendered manuscript](https://manubot.github.io/rootstock/). Within a paragraph in markdown, single newlines are interpreted as whitespace (same as a space). A paragraph's source does not need to contain newlines. @@ -104,12 +104,26 @@ When choosing which source to use for a citation, we recommend the following ord Similarly, `@https://doi.org/10.1101/142760` is a [workaround](https://github.com/manubot/manubot/issues/16) to set the journal name of bioRxiv preprints to _bioRxiv_. 7. Wikidata Items, cite like `@wikidata:Q50051684`. Note that anyone can edit or add records on [Wikidata](https://www.wikidata.org), so users are encouraged to contribute metadata for hard-to-cite works to Wikidata. -8. Any other compact identifier supported by . - Manubot uses the Identifiers.org Resolution Service to support [hundreds](https://github.com/manubot/manubot/blob/7055bcc6524fdf1ef97d838cf0158973e2061595/manubot/cite/handlers.py#L122-L831 "Actual prefix support is determined by this manubot source code.") of [prefixes](https://registry.identifiers.org/registry "Identifiers.org prefix search"). - For example, citing `@clinicaltrials:NCT04280705` will produce the same bibliographic metadata as `@https://identifiers.org/clinicaltrials:NCT04280705` or `@https://clinicaltrials.gov/ct2/show/NCT04280705`. -9. For references that do not have any of the above persistent identifiers, the citation key does not need to include a prefix. +8. Any other compact identifier supported by . + Manubot uses the Bioregistry to support [hundreds](https://github.com/manubot/manubot/blob/a4af68125ab6bb322fdfb1689cfeec09f0cb1b60/manubot/cite/handlers.py#L155-L1485 "Actual prefix support is determined by this manubot source code.") of [prefixes](https://bioregistry.io/registry/ "Bioregistry prefix search"). + For example, citing `@clinicaltrials:NCT04280705` will produce the same bibliographic metadata as `@https://bioregistry.io/clinicaltrials:NCT04280705` or `@https://clinicaltrials.gov/ct2/show/NCT04280705`. +9. For references that do not have any of the above persistent identifiers, + the citation key does not need to include a prefix. Citing `@old-manuscript` will work, but only if reference metadata is [provided manually](#reference-metadata). +Manubot is able to infer certain prefixes, +such some citations can be formatted like `@accession` (without a prefix). +Examples includes DOIs like `@10.15363/thinklab.4` or `@10/993`, +PMC / PubMed identifiers like `@PMC4497619` or `@26158728`, +arXiv identifier like `@1508.06576v2`, +and Wikidata identifiers like `@Q50051684`. +To disable citekey prefix inference, add the following to `metadata.yaml`: + +```yaml +pandoc: + manubot-infer-citekey-prefixes: false +``` + Cite multiple items at once like: ```md @@ -120,14 +134,23 @@ Note that multiple citations must be semicolon separated. Be careful not to cite the same study using identifiers from multiple sources. For example, the following citations all refer to the same study, but will be treated as separate references: `[@doi:10.7717/peerj.705; @pmc:PMC4304851; @pubmed:25648772]`. -Citation keys must adhere to the syntax described in the [Pandoc manual](https://pandoc.org/MANUAL.html#citations): +The citation key syntax is described in the [Pandoc manual](https://pandoc.org/MANUAL.html#citation-syntax): -> The citation key must begin with a letter, digit, or `_`, and may contain alphanumerics, `_`, and internal punctuation characters (`:.#$%&-+?<>~/`). +> Unless a citation key start with a letter, digit, or `_`, +> and contains only alphanumerics and internal punctuation characters (`:.#$%&-+?<>~/`), +> it must be surrounded by curly braces, +> which are not considered part of the key. +> In `@Foo_bar.baz.`, the key is `Foo_bar.baz`. +> The final period is not *internal* punctuation, +> so it is not included in the key. +> In `@{Foo_bar.baz.}`, the key is `Foo_bar.baz.`, including the final period. +> The curly braces are recommended if you use URLs as keys: +> `[@{https://example.com/bib?name=foobar&date=2000}, p. 33]`. -To evaluate whether a citation key fully matches this syntax, try [this online regex](https://regex101.com/r/mXZyY2/latest). -If the citation key is not valid, use the [citation aliases](#citation-aliases) workaround below. -This is required for citation keys that contain forbidden characters such as `;` or `=` or end with a non-alphanumeric character such as `/`. - +If a citation key does not fully match [this online regex](https://regex101.com/r/mXZyY2/latest) +(for example, contains characters such as `;` or `=` or end with a non-alphanumeric character such as `/`), +make sure to surround it with curly braces or use the [citation aliases](#citation-aliases) workaround below. + Prior to Rootstock commit [`6636b91`](https://github.com/manubot/rootstock/commit/6636b912c6b41593acd2041d34cd4158c1b317fb) on 2020-01-14, Manubot processed citations separately from Pandoc. Switching to a Pandoc filter improved reliability on complex documents, but restricted the syntax of citation keys slightly. @@ -136,7 +159,7 @@ By default, `pandoc-manubot-cite` does not fail upon invalid citations, although ```yaml pandoc: - manubot-fail-on-errors: True + manubot-fail-on-errors: true ``` #### Citation aliases @@ -177,7 +200,7 @@ Manubot stores the bibliographic details for references (the set of all cited wo Manubot automatically generates CSL JSON for most persistent identifiers (as described in [Citations](#citations) above). In some cases, automatic metadata retrieval fails or provides incorrect or incomplete information. Errors are most common for references generated from scraping HTML metadata from websites. -This occurs most frequently for `https`/`http`/`url` citations as well as identifiers.org prefixes without explicit support listed above. +This occurs most frequently for `https`/`http`/`url` citations as well as Bioregistry prefixes without explicit support listed above. Therefore, Manubot supports user-provided metadata, which we refer to as "manual references". When a manual reference is provided, Manubot uses the supplied metadata and does not attempt to generate it. @@ -237,6 +260,7 @@ initials: DSH # optional orcid: 0000-0002-3012-7446 # mandatory twitter: dhimmel # optional email: daniel.himmelstein@gmail.com # suggested +corresponding: true # optional, if set to true displays author's email for correspondence affiliations: # as a list, strongly suggested - Department of Systems Pharmacology and Translational Therapeutics, University of Pennsylvania - Department of Biological & Medical Informatics, University of California, San Francisco diff --git a/build/README.md b/build/README.md index f6087cf7..28893abe 100644 --- a/build/README.md +++ b/build/README.md @@ -8,7 +8,7 @@ For example, run local builds using the command `BUILD_PDF=false bash build/buil To build a DOCX file of the manuscript, set the `BUILD_DOCX` environment variable to `true`. For example, use the command `BUILD_DOCX=true bash build/build.sh`. -To export DOCX for all CI builds, set an environment variable (see docs for [GitHub Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables) or [Travis CI](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings)). +To export DOCX for all CI builds, set an environment variable (see docs for [GitHub Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables)). Currently, equation numbers via `pandoc-eqnos` are not supported for DOCX output. Format conversion is done using [Pandoc](https://pandoc.org/MANUAL.html). diff --git a/build/assets/style.csl b/build/assets/style.csl index 942a0434..b836f7b9 100644 --- a/build/assets/style.csl +++ b/build/assets/style.csl @@ -47,7 +47,7 @@ - + diff --git a/build/build.sh b/build/build.sh index 4dd74373..68b0b922 100755 --- a/build/build.sh +++ b/build/build.sh @@ -11,6 +11,21 @@ export TZ=Etc/UTC # Default Python to read/write text files using UTF-8 encoding export LC_ALL=en_US.UTF-8 + +# Set DOCKER_RUNNING to true if docker is running, otherwise false. +DOCKER_RUNNING="$(docker info &> /dev/null && echo "true" || (true && echo "false"))" + +# Set option defaults +CI="${CI:-false}" +BUILD_PDF="${BUILD_PDF:-true}" +BUILD_DOCX="${BUILD_DOCX:-false}" +BUILD_LATEX="${BUILD_LATEX:-false}" +SPELLCHECK="${SPELLCHECK:-false}" +MANUBOT_USE_DOCKER="${MANUBOT_USE_DOCKER:-$DOCKER_RUNNING}" +# Pandoc's configuration is specified via files of option defaults +# located in the $PANDOC_DATA_DIR/defaults directory. +PANDOC_DATA_DIR="${PANDOC_DATA_DIR:-build/pandoc}" + # Generate reference information echo >&2 "Retrieving and processing reference metadata" manubot process \ @@ -20,10 +35,6 @@ manubot process \ --skip-citations \ --log-level=INFO -# Pandoc's configuration is specified via files of option defaults -# located in the $PANDOC_DATA_DIR/defaults directory. -PANDOC_DATA_DIR="${PANDOC_DATA_DIR:-build/pandoc}" - # Make output directory mkdir -p output @@ -35,12 +46,9 @@ pandoc --verbose \ --defaults=common.yaml \ --defaults=html.yaml -# Set DOCKER_RUNNING to a non-empty string if docker is running, otherwise null. -DOCKER_RUNNING="$(docker info &> /dev/null && echo "yes" || true)" - # Create PDF output (unless BUILD_PDF environment variable equals "false") # If Docker is not available, use WeasyPrint to create PDF -if [ "${BUILD_PDF:-}" != "false" ] && [ -z "$DOCKER_RUNNING" ]; then +if [ "${BUILD_PDF}" != "false" ] && [ "${MANUBOT_USE_DOCKER}" != "true" ]; then echo >&2 "Exporting PDF manuscript using WeasyPrint" if [ -L images ]; then rm images; fi # if images is a symlink, remove it ln -s content/images @@ -53,9 +61,9 @@ if [ "${BUILD_PDF:-}" != "false" ] && [ -z "$DOCKER_RUNNING" ]; then fi # If Docker is available, use athenapdf to create PDF -if [ "${BUILD_PDF:-}" != "false" ] && [ -n "$DOCKER_RUNNING" ]; then +if [ "${BUILD_PDF}" != "false" ] && [ "${MANUBOT_USE_DOCKER}" == "true" ]; then echo >&2 "Exporting PDF manuscript using Docker + Athena" - if [ "${CI:-}" = "true" ]; then + if [ "${CI}" = "true" ]; then # Incease --delay for CI builds to ensure the webpage fully renders, even when the CI server is under high load. # Local builds default to a shorter --delay to minimize runtime, assuming proper rendering is less crucial. MANUBOT_ATHENAPDF_DELAY="${MANUBOT_ATHENAPDF_DELAY:-5000}" @@ -78,7 +86,7 @@ if [ "${BUILD_PDF:-}" != "false" ] && [ -n "$DOCKER_RUNNING" ]; then fi # Create DOCX output (if BUILD_DOCX environment variable equals "true") -if [ "${BUILD_DOCX:-}" = "true" ]; then +if [ "${BUILD_DOCX}" = "true" ]; then echo >&2 "Exporting Word Docx manuscript" pandoc --verbose \ --data-dir="$PANDOC_DATA_DIR" \ @@ -86,9 +94,18 @@ if [ "${BUILD_DOCX:-}" = "true" ]; then --defaults=docx.yaml fi +# Create LaTeX output (if BUILD_LATEX environment variable equals "true") +if [ "${BUILD_LATEX}" = "true" ]; then + echo >&2 "Exporting LaTeX manuscript" + pandoc \ + --data-dir="$PANDOC_DATA_DIR" \ + --defaults=common.yaml \ + --defaults=latex.yaml +fi + # Spellcheck -if [ "${SPELLCHECK:-}" = "true" ]; then - export ASPELL_CONF="add-extra-dicts $(pwd)/build/assets/custom-dictionary.txt; ignore-case false" +if [ "${SPELLCHECK}" = "true" ]; then + export ASPELL_CONF="add-extra-dicts $(pwd)/build/assets/custom-dictionary.txt; ignore-case true" # Identify and store spelling errors pandoc \ diff --git a/build/environment.yml b/build/environment.yml index 5593065e..65f71bc6 100644 --- a/build/environment.yml +++ b/build/environment.yml @@ -2,36 +2,36 @@ name: manubot channels: - conda-forge dependencies: - - cairo=1.14.12 - - cairocffi=0.8.0 - - cffi=1.12.3 - - ghp-import=0.5.5 - - jinja2=2.11.2 - - jsonschema=3.2.0 - - pandoc=2.9.2 - - panflute=1.12.5 - - pango=1.40.14 - - pip=20.2 - - psutil=5.7.3 - - python=3.7.8 - - pyyaml=5.3 - - requests=2.24.0 + - cairo=1.16.0 + - cairocffi=1.2.0 + - ghp-import=2.0.2 + - jinja2=3.0.3 + - jsonschema=4.2.1 + - pandoc=2.17.0.1 + - pango=1.48.10 + - pip=21.3.1 + - python=3.10.0 + - requests-cache=0.8.1 + - requests=2.26.0 - toml=0.10.2 - - watchdog=0.10.3 - - yamllint=1.25.0 + - watchdog==2.1.6 + - weasyprint=53.4 + - yamllint=1.26.3 - pip: + - cffi==1.15.0 - errorhandler==2.0.1 - - git+https://github.com/manubot/manubot@7c03b4a7d42506b3241e58cd5643a028443b9b9d - - isbnlib==3.10.3 - - markupsafe==2.0.1 + - git+https://github.com/manubot/manubot@90925eeff90e3aaacaa504fc9a47107609cffc17 + - isbnlib==3.10.9 - opentimestamps-client==0.7.0 - opentimestamps==0.4.1 - - pandoc-eqnos==2.3.0 - - pandoc-fignos==2.3.1 - - pandoc-tablenos==2.2.2 - - pandoc-xnos==2.4.3 + - pandoc-eqnos==2.5.0 + - pandoc-fignos==2.4.0 + - pandoc-tablenos==2.3.0 + - pandoc-xnos==2.5.0 + - pandocfilters==1.5.0 + - panflute==2.1.0 + - psutil==5.8.0 - pybase62==0.4.3 - pysha3==1.0.2 - python-bitcoinlib==0.10.2 - - requests-cache==0.5.2 - - weasyprint==0.42.3 + - pyyaml==5.4.1 diff --git a/build/pandoc/defaults/common.yaml b/build/pandoc/defaults/common.yaml index 12c0c343..bfa5d971 100644 --- a/build/pandoc/defaults/common.yaml +++ b/build/pandoc/defaults/common.yaml @@ -6,7 +6,7 @@ filters: - pandoc-eqnos - pandoc-tablenos - pandoc-manubot-cite -- pandoc-citeproc +- citeproc wrap: preserve metadata: csl: build/assets/style.csl diff --git a/build/pandoc/defaults/html.yaml b/build/pandoc/defaults/html.yaml index 956bbbc2..8aff336a 100644 --- a/build/pandoc/defaults/html.yaml +++ b/build/pandoc/defaults/html.yaml @@ -3,22 +3,29 @@ to: html5 output-file: output/manuscript.html # include-before-body: -# - build/plugins/d3.html +### third-party plugins +#- build/plugins/d3.html include-after-body: +### theme - build/themes/default.html -# - build/plugins/inline-svg.html -- build/plugins/anchors.html +### first-party plugins +- build/plugins/core.html # needed for all first-party plugins - build/plugins/accordion.html -- build/plugins/tooltips.html +- build/plugins/anchors.html +- build/plugins/attributes.html +#- build/plugins/inline-svg.html - build/plugins/jump-to-first.html +- build/plugins/lightbox.html - build/plugins/link-highlight.html - build/plugins/table-of-contents.html -- build/plugins/lightbox.html -- build/plugins/attributes.html -- build/plugins/math.html -- build/plugins/hypothesis.html +- build/plugins/tooltips.html +### third-party plugins - build/plugins/analytics.html +- build/plugins/hypothesis.html +- build/plugins/mathjax.html +#- build/plugins/scite.html variables: - math: '' + document-css: false + math: "" html-math-method: method: mathjax diff --git a/build/pandoc/defaults/latex.yaml b/build/pandoc/defaults/latex.yaml new file mode 100644 index 00000000..481302d1 --- /dev/null +++ b/build/pandoc/defaults/latex.yaml @@ -0,0 +1,4 @@ +# Pandoc --defaults for LaTeX output. +# Load on top of common defaults. +to: latex +output-file: output/manuscript.tex diff --git a/build/plugins/accordion.html b/build/plugins/accordion.html index eaddd546..f6201356 100644 --- a/build/plugins/accordion.html +++ b/build/plugins/accordion.html @@ -1,272 +1,146 @@ - - - + + diff --git a/build/plugins/analytics.html b/build/plugins/analytics.html index 0e641a12..cbab5326 100644 --- a/build/plugins/analytics.html +++ b/build/plugins/analytics.html @@ -1,3 +1,5 @@ - - - + diff --git a/build/plugins/anchors.html b/build/plugins/anchors.html index 4f2e6ba3..7149501b 100644 --- a/build/plugins/anchors.html +++ b/build/plugins/anchors.html @@ -1,144 +1,128 @@ - - - + + diff --git a/build/plugins/attributes.html b/build/plugins/attributes.html index b968198c..85077da0 100644 --- a/build/plugins/attributes.html +++ b/build/plugins/attributes.html @@ -1,130 +1,85 @@ - - - diff --git a/build/plugins/core.html b/build/plugins/core.html new file mode 100644 index 00000000..4c680a4d --- /dev/null +++ b/build/plugins/core.html @@ -0,0 +1,129 @@ + + + diff --git a/build/plugins/d3.html b/build/plugins/d3.html index 48c16d80..d04226e2 100644 --- a/build/plugins/d3.html +++ b/build/plugins/d3.html @@ -1,16 +1,12 @@ - + + src="https://cdnjs.cloudflare.com/ajax/libs/d3/6.2.0/d3.min.js" + integrity="sha512-C2RveGuPIWqkaLAluvoxyiaN1XYNe5ss11urhZWZYBUA9Ydgj+hfGKPcxCzTwut1/fmjEZR7Ac35f2aycT8Ogw==" + crossorigin="anonymous" +> diff --git a/build/plugins/hypothesis.html b/build/plugins/hypothesis.html index 7bd1691e..3cd5e108 100644 --- a/build/plugins/hypothesis.html +++ b/build/plugins/hypothesis.html @@ -1,104 +1,166 @@ - - - + + diff --git a/build/plugins/inline-svg.html b/build/plugins/inline-svg.html index be402422..619a3a18 100644 --- a/build/plugins/inline-svg.html +++ b/build/plugins/inline-svg.html @@ -1,62 +1,53 @@ - - - diff --git a/build/plugins/jump-to-first.html b/build/plugins/jump-to-first.html index e8a8088f..da7df4a9 100644 --- a/build/plugins/jump-to-first.html +++ b/build/plugins/jump-to-first.html @@ -1,272 +1,104 @@ - - - + + diff --git a/build/plugins/lightbox.html b/build/plugins/lightbox.html index 6b9f2ae6..1fbdf771 100644 --- a/build/plugins/lightbox.html +++ b/build/plugins/lightbox.html @@ -1,620 +1,660 @@ - - - + + diff --git a/build/plugins/link-highlight.html b/build/plugins/link-highlight.html index 4462f509..04263a83 100644 --- a/build/plugins/link-highlight.html +++ b/build/plugins/link-highlight.html @@ -1,184 +1,157 @@ - - - + + diff --git a/build/plugins/math.html b/build/plugins/math.html deleted file mode 100644 index f47b24d5..00000000 --- a/build/plugins/math.html +++ /dev/null @@ -1,27 +0,0 @@ - - - - - - - diff --git a/build/plugins/mathjax.html b/build/plugins/mathjax.html new file mode 100644 index 00000000..14ba331f --- /dev/null +++ b/build/plugins/mathjax.html @@ -0,0 +1,53 @@ + + + + + + + diff --git a/build/plugins/scite.html b/build/plugins/scite.html new file mode 100644 index 00000000..60bb9a67 --- /dev/null +++ b/build/plugins/scite.html @@ -0,0 +1,62 @@ + + + + + + + diff --git a/build/plugins/table-of-contents.html b/build/plugins/table-of-contents.html index e4159457..ea24c97e 100644 --- a/build/plugins/table-of-contents.html +++ b/build/plugins/table-of-contents.html @@ -1,315 +1,404 @@ - + + diff --git a/build/plugins/tooltips.html b/build/plugins/tooltips.html index f9cbc60e..e023e3a7 100644 --- a/build/plugins/tooltips.html +++ b/build/plugins/tooltips.html @@ -1,614 +1,507 @@ - - - + + diff --git a/build/themes/default.html b/build/themes/default.html index 4022f31a..b3298fe7 100644 --- a/build/themes/default.html +++ b/build/themes/default.html @@ -1,60 +1,533 @@ diff --git a/ci/.gitignore b/ci/.gitignore index f50cd000..6c5fe923 100644 --- a/ci/.gitignore +++ b/ci/.gitignore @@ -1,5 +1,2 @@ # SSH public and private keys deploy.key* - -# Output from travis encrypt-file (legacy) -travis-encrypt-file.log diff --git a/ci/README.md b/ci/README.md index db6ccca3..3e89fc2b 100644 --- a/ci/README.md +++ b/ci/README.md @@ -1,7 +1,7 @@ # Continuous integration tools This directory contains tools and files for continuous integration (CI). -Specifically, [`deploy.sh`](deploy.sh) runs on successful `master` branch builds that are not pull requests. +Specifically, [`deploy.sh`](deploy.sh) runs on successful `main` branch builds that are not pull requests. The contents of `../webpage` are committed to the `gh-pages` branch. The contents of `../output` are committed to the `output` branch. diff --git a/ci/deploy.sh b/ci/deploy.sh index b948ae67..f6788a02 100755 --- a/ci/deploy.sh +++ b/ci/deploy.sh @@ -7,12 +7,10 @@ set -o errexit \ -o nounset \ -o pipefail -# set environment variables for either Travis or GitHub Actions -REPO_SLUG=${TRAVIS_REPO_SLUG:-$GITHUB_REPOSITORY} -COMMIT=${TRAVIS_COMMIT:-$GITHUB_SHA} -CI_BUILD_WEB_URL=${CI_BUILD_WEB_URL:-$TRAVIS_BUILD_WEB_URL} -CI_JOB_WEB_URL=${CI_JOB_WEB_URL:-$TRAVIS_JOB_WEB_URL} -BRANCH=${TRAVIS_BRANCH:-master} +# set environment variables for GitHub Actions +REPO_SLUG=${GITHUB_REPOSITORY} +COMMIT=${GITHUB_SHA} +BRANCH=${DEFAULT_BRANCH:-main} # Add commit hash to the README OWNER_NAME="$(dirname "$REPO_SLUG")" @@ -48,21 +46,12 @@ set +o xtrace # disable xtrace in subshell for private key operations if [ -v MANUBOT_SSH_PRIVATE_KEY ]; then base64 --decode <<< "$MANUBOT_SSH_PRIVATE_KEY" | ssh-add - else -echo >&2 "DeprecationWarning: Loading deploy.key from an encrypted file. -In the future, using the MANUBOT_ACCESS_TOKEN or MANUBOT_SSH_PRIVATE_KEY environment variable may be required." -openssl aes-256-cbc \ - -K $encrypted_700259e19daf_key \ - -iv $encrypted_700259e19daf_iv \ - -in ci/deploy.key.enc \ - -out ci/deploy.key -d -chmod 600 ci/deploy.key -ssh-add ci/deploy.key + echo >&2 "Deployment will fail since neither of the following environment variables are set: MANUBOT_ACCESS_TOKEN or MANUBOT_SSH_PRIVATE_KEY." fi ) fi # Fetch and create gh-pages and output branches -# Travis does a shallow and single branch git clone git remote set-branches --add origin gh-pages output git fetch origin gh-pages:gh-pages output:output || \ echo >&2 "[INFO] could not fetch gh-pages or output from origin." diff --git a/ci/install.sh b/ci/install.sh index 61928d75..c264b08e 100755 --- a/ci/install.sh +++ b/ci/install.sh @@ -1,15 +1,15 @@ #!/usr/bin/env bash -## install.sh: run during a Travis CI or AppVeyor build to install the conda environment +## install.sh: run during an AppVeyor build to install the conda environment ## and the optional Pandoc spellcheck dependencies. # Set options for extra caution & debugging set -o errexit \ -o pipefail -wget https://repo.continuum.io/miniconda/Miniconda3-4.7.12.1-Linux-x86_64.sh \ - --output-document miniconda.sh -bash miniconda.sh -b -p $HOME/miniconda +wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge-pypy3-$(uname)-$(uname -m).sh \ + --output-document miniforge.sh +bash miniforge.sh -b -p $HOME/miniconda source $HOME/miniconda/etc/profile.d/conda.sh hash -r conda config \ diff --git a/content/00.front-matter.md b/content/00.front-matter.md index 0657a639..2cde88fb 100644 --- a/content/00.front-matter.md +++ b/content/00.front-matter.md @@ -27,7 +27,9 @@ on {{manubot.date}}. {## Template for listing authors ##} {% for author in manubot.authors %} -+ **{{author.name}}**
++ **{{author.name}}** + {% if author.corresponding is defined and author.corresponding == true -%}^[✉](#correspondence)^{%- endif -%} +
{%- if author.orcid is defined and author.orcid is not none %} ![ORCID icon](images/orcid.png){.inline_icon} [{{author.orcid}}](https://orcid.org/{{author.orcid}}) diff --git a/output/README.md b/output/README.md index fbdc3a6d..12d8f517 100644 --- a/output/README.md +++ b/output/README.md @@ -1,8 +1,8 @@ # Generated citation / reference files The `output` branch contains files automatically generated by the manuscript build process. -It consists of the contents of the `output` directory of the `master` branch. -These files are not tracked in `master`, but instead written to the `output` branch by continuous integration builds. +It consists of the contents of the `output` directory of the `main` branch. +These files are not tracked in `main`, but instead written to the `output` branch by continuous integration builds. ## Files diff --git a/setup.bash b/setup.bash new file mode 100755 index 00000000..4319cc33 --- /dev/null +++ b/setup.bash @@ -0,0 +1,228 @@ +#!/bin/bash +# Setup Manubot +# Based on https://github.com/manubot/rootstock/blob/main/SETUP.md +# This is designed to be run from the bash terminal + +# Stop on first error. +set -e + +usage() { +echo "Usage: $0 [--owner text] [--repo text] [--yes]" +echo "Guides the user through the creation of a new Manubot repository for their manuscript." +echo +echo "If no options are supplied a fully interactive process is used." +echo "OWNER and REPO refer to the details of your manuscript repo location:" +echo "i.e. https://github.com/OWNER/REPO." +echo +echo "Options:" +echo " -o --owner GitHub user or organisation name." +echo " -r --repo Name of the repository for your new manuscript." +echo " -y --yes Non-interactive mode. Continue script without asking for confirmation that the repo exists." +echo " -s --ssh Use SSH to authenticate GitHub account. HTTPS is used by default." +echo " Option only effective if --yes is also set, otherwise answer given in user interaction takes precedence." +echo " -h --help Display usage information." +1>&2; exit 1; } + +# Check if to continue +check(){ +while true +do + echo "Once you have created your repo press enter to continue setup," + read -r -p "or type exit to quit now: " input + + case $input in + "") + echo + echo "Continuing Setup..." + echo + break + ;; + [eE][xX][iI][tT]) + exit 1 + ;; + *) + echo + echo "Invalid input, try again..." + echo + ;; + esac +done +} + +# Option strings +SHORT=o:r:hys +LONG=owner:,repo:,help,yes,ssh + +YES=0 # continue when prompted +AUTH=0 # used https or ssh auth + +# read the options +OPTS=$(getopt --options $SHORT --long $LONG --name "$0" -- "$@") + +if [ $? != 0 ] ; then echo "Failed to parse options...exiting." >&2 ; exit 1 ; fi + +eval set -- "$OPTS" + +# extract options and their arguments into variables. +while true ; do + case "$1" in + -o | --owner ) + shift; + OWNER=$1 + shift + ;; + -r | --repo ) + REPO="$2" + shift 2 + ;; + -y | --yes ) + YES=1 + shift + ;; + -s | --ssh ) + AUTH=1; + shift + ;; + -- ) + shift + break + ;; + -h | --help ) + shift + usage + exit 1 + ;; + *) + echo "Internal error!" + exit 1 + ;; + esac +done + +if [ -z "${OWNER}" ] || [ -z "${REPO}" ]; then + echo "This script will take you through the setup process for Manubot." + echo "First, we need to specify where to create the GitHub repo for your manuscript." + echo + echo "The URL will take this format: https://github.com/OWNER/REPO." + echo "OWNER is your username or organisation" + echo "REPO is the name of your repository" + echo + read -r -p "Type in the OWNER now:" input + OWNER=$input + read -r -p "Type in the REPO now:" input + REPO=$input +fi + +# If using interactive mode, check remote repo exists. +if [[ "$YES" == '0' ]]; then + while true + do + echo + read -r -p "Have you manually created https://github.com/${OWNER}/${REPO}? [y/n] " input + + case $input in + [yY][eE][sS]|[yY]) + + echo + echo "Continuing Setup..." + echo + break + ;; + [nN][oO]|[nN]) + echo + echo "Go to https://github.com/new and create https://github.com/${OWNER}/${REPO}" + echo "Note: the new repo must be completely empty or the script will fail." + echo + check + break + ;; + *) + echo + echo "Invalid input, try again..." + echo + ;; + esac + done +else + echo "Setting up https://github.com/${OWNER}/${REPO}" +fi + +# Clone manubot/rootstock +echo +echo "Cloning Rootstock..." +echo +git clone --single-branch https://github.com/manubot/rootstock.git ${REPO} +cd ${REPO} + +echo +echo "Setup tracking of remote..." + +# Configure remotes +git remote add rootstock https://github.com/manubot/rootstock.git + +# Check auth method +if [[ "$YES" == '0' ]]; then + while true + do + echo + read -r -p "Would you like to use SSH to authenticate your GitHub account? [y/n] " input + + case $input in + [yY][eE][sS]|[yY]) + AUTH=1 + break + ;; + [nN][oO]|[nN]) + AUTH=0 + break + ;; + *) + echo + echo "Invalid input, try again..." + echo + ;; + esac + done +fi + +case $AUTH in + 0) + echo + echo "Seting origin URL using its https web address" + echo + git remote set-url origin https://github.com/${OWNER}/${REPO}.git + ;; + 1) + echo + echo "Seting origin URL using SSH" + echo + git remote set-url origin git@github.com:$OWNER/$REPO.git + ;; +esac + +git push --set-upstream origin main + +# To use GitHub Actions only: +echo "Setup for GitHub Actions ONLY..." +# remove AppVeyor config +git rm .appveyor.yml +# remove ci/install.sh (only used by AppVeyor) +git rm ci/install.sh + +# Update README +echo "Updating README..." +# Perform substitutions +sed "s/manubot\/rootstock/${OWNER}\/${REPO}/g" README.md > tmp && mv -f tmp README.md +sed "s/manubot\.github\.io\/rootstock/${OWNER}\.github\.io\/${REPO}/g" README.md > tmp && mv -f tmp README.md + +echo "Committing rebrand..." +git add --update +git commit --message "Brand repo to $OWNER/$REPO" +git push origin main +echo +echo "Setup complete" +echo +echo "The new repo has been created at $(pwd)" +echo +echo "A good first step is to modify content/metadata.yaml with the relevant information for your manuscript." +echo diff --git a/webpage/README.md b/webpage/README.md index 9e22c56d..739f4977 100644 --- a/webpage/README.md +++ b/webpage/README.md @@ -6,7 +6,7 @@ To redirect to the permalink for the latest manuscript version at anytime, use t ## Files -This directory contains the following files, which are mostly ignored on the `master` branch: +This directory contains the following files, which are mostly ignored on the `main` branch: + [`index.html`](index.html) is an HTML manuscript. + [`manuscript.pdf`](manuscript.pdf) is a PDF manuscript.