diff --git a/assets/styles/style.css b/assets/styles/style.css index e807b22..56900c4 100644 --- a/assets/styles/style.css +++ b/assets/styles/style.css @@ -9,3 +9,42 @@ body { [aria-label="Document Outline"] { max-height: calc(100vh - 100px) !important; } + +.myst-static-input-wrapper { + border: 1px solid #ccc; +} + +.myst-static-input-wrapper::before { + content: "๐Ÿ“ฅ MyST input"; + display: block; + background-color: #f5f5f5; + border-bottom: 1px solid #ccc; + padding: 8px 12px; + font-weight: bold; + font-size: 14px; + color: #333; + margin: 0; +} + +.myst-static-output-wrapper { + border: 1px solid #ccc; + margin-bottom: 20px; +} + +.myst-static-output-wrapper::before { + content: "๐Ÿ“ค MyST output"; + display: block; + background-color: #f5f5f5; + border-bottom: 1px solid #ccc; + padding: 8px 12px; + font-weight: bold; + font-size: 14px; + color: #333; + margin: 0; +} + +.myst-static-content { + padding-left: 12px; + padding-right: 12px; + margin: 0; +} diff --git a/for-instructors/helpers.md b/for-instructors/helpers.md new file mode 100644 index 0000000..24c78f8 --- /dev/null +++ b/for-instructors/helpers.md @@ -0,0 +1,25 @@ +# ๐Ÿช„ Helpers + +This repository includes a `plugin-custom-directives.mjs` file which defines custom +directives that will save some time authoring certain repeated elements. + +## Git commit checkpoint directive + +```{myst:static} +:::{gitCommitCheckpoint} my commit message +::: +``` + + +## "You should notice..." directive + +``````{myst:static} +:::{youShouldNotice} +...the `{youShouldNotice}` directive fully supports markdown in the body. +This means you can, for example include some code: + +```python +print("Some code!") +``` +::: +`````` diff --git a/for-instructors/style-guide.md b/for-instructors/style-guide.md index f5d01a1..f3753bf 100644 --- a/for-instructors/style-guide.md +++ b/for-instructors/style-guide.md @@ -209,6 +209,30 @@ E.g.: ::: ``` +**As a shortcut, you can use the `{youShouldNotice}` directive.** +See [](./helpers.md). + + +#### Committing + +Use ๐Ÿ’พ in a callout to indicate that the user should stop and do a commit now. +Provide the full set of commands the user should run. + +``````{myst} +:::{important} ๐Ÿ’พ Commit & push to GitHub +:icon: false + +```bash +git add . +git commit -m "Commit message" +git push -u origin main +``` +::: +`````` + +**As a shortcut, you can use the `{gitCommitCheckpoint}` directive.** +See [](./helpers.md). + ### Voice / language diff --git a/modules/05-sharing-and-publishing/github-actions-deploy-successful.jpg b/modules/05-sharing-and-publishing/github-actions-deploy-successful.jpg new file mode 100644 index 0000000..66c2215 Binary files /dev/null and b/modules/05-sharing-and-publishing/github-actions-deploy-successful.jpg differ diff --git a/modules/05-sharing-and-publishing/github-create-a-release.jpg b/modules/05-sharing-and-publishing/github-create-a-release.jpg new file mode 100644 index 0000000..64c29cb Binary files /dev/null and b/modules/05-sharing-and-publishing/github-create-a-release.jpg differ diff --git a/modules/05-sharing-and-publishing/github-repo-about-cog.jpg b/modules/05-sharing-and-publishing/github-repo-about-cog.jpg new file mode 100644 index 0000000..20e924d Binary files /dev/null and b/modules/05-sharing-and-publishing/github-repo-about-cog.jpg differ diff --git a/modules/05-sharing-and-publishing/index.md b/modules/05-sharing-and-publishing/index.md index 9e0d57d..f5c3f7f 100644 --- a/modules/05-sharing-and-publishing/index.md +++ b/modules/05-sharing-and-publishing/index.md @@ -77,7 +77,8 @@ Markdown text. Let's jump right into a quick example of how this functionality works. -#### Example `{glossary}` directive and `{term}` role +#### Example directive and role + :::{tip} ๐Ÿ’ช Mini-exercise :icon: false @@ -97,6 +98,11 @@ Try hovering over the word "Term" to see a definition. ``` +##### ๐Ÿง  What do we know now? + +The `{glossary}` role enables defining terms, and the `{term}` role enables referencing +terms. + ### MySTMD, the software @@ -118,17 +124,7 @@ use of the terminal. To preview a MyST site in JupyterLab, view instructions at [](../../reference/04-using-myst.md). -:::{important} ๐Ÿ‘€ You should notice... -:class: simple -:icon: false - -...when you trigger the build as specified in the instructions linked above, a loading -screen is displayed. - -After a few seconds, the build will complete and you can see your fully-built site! -::: - -:::{note} The normal way +:::{note} The normal way (without JupyterLab) :class: dropdown Because we're working in CryoCloud for this workshop, we'll be following the @@ -153,8 +149,43 @@ myst start ### ๐Ÿ’ช Exercise A: Build _this_ MyST website in JupyterLab -_TODO_: Step to clone workshop repo as a drop-down or link to reference page (for -participants who may come in late and miss these instructions from earlier modules) +This workshop's materials are built with MyST. +We'll build this premade website together on CryoCloud so you can get used to the +process. + +::::::{hint} Joining late? You may need to clone the workshop repository +:class: dropdown + +Foo! + +If you're joining late, you may have missed a prior instruction to clone the workshop +website and set up GitHub authentication. + +Open a terminal in your CryoCloud JupyterLab server: + +```bash +cd # Move to your home directory +git clone https://github.com/geojupyter/workshop-open-source-geospatial.git +``` + +:::{youShouldNotice} +...this command produces output like: + +``` +Cloning into 'workshop-open-source-geospatial'... +remote: Enumerating objects: 417, done. +remote: Counting objects: 100% (178/178), done. +remote: Compressing objects: 100% (101/101), done. +remote: Total 417 (delta 136), reused 97 (delta 77), pack-reused 239 (from 2) +Receiving objects: 100% (417/417), 1.13 MiB | 7.21 MiB/s, done. +Resolving deltas: 100% (229/229), done. +``` +::: + +**You'll need to setup GitHub authentication to push to GitHub**, which is required to +complete this module. +Please follow the instructions at [](../../reference/03-gh-auth.md). +:::::: #### Navigate to the correct directory in the file browser @@ -163,10 +194,7 @@ On the left panel, ensure the JupyterLab file browser tab (๐Ÿ“ icon) is selecte Double click the folder in the file browser named `workshop-open-source-geospatial`. -:::{important} ๐Ÿ‘€ You should notice... -:class: simple -:icon: false - +:::{youShouldNotice} ...a listing of around a dozen files and directories, including Markdown files and a file named `myst.yml`. ::: @@ -174,14 +202,11 @@ file named `myst.yml`. #### Build the MyST website -Location the MyST project configuration file, `myst.yml`, in the file browser. +Locate the MyST project configuration file, `myst.yml`, in the file browser. Right click this file and select the top option from the menu: "Build MyST Project". -:::{important} ๐Ÿ‘€ You should notice... -:class: simple -:icon: false - +:::{youShouldNotice} ...a new browser tab opens with a loading spinner and the title "Building MyST Site". After around 5 seconds, the build will complete and the website content will display @@ -201,6 +226,31 @@ At the top-right is a button with the text "Rebuild". ### ๐Ÿ’ช Exercise B: Build a MyST website _from scratch_ in JupyterLab +:::{important} Not covered: _Environment management!_ +:class: dropdown + +Environment management is an important part of reproducible research. +Always include an environment manifest or specification alongside your publication. + +This exercise works as shown on CryoCloud because CryoCloud has MySTMD and many other +dependencies pre-installed. +When working on your own, you may encounter an error like: + +``` +Command 'myst' not found +``` + +We highly recommend that you try [pixi](https://pixi.sh/) as a dependency manager: +it's fast, user-friendly, and makes following best practices easy or automatic. + +```bash +pixi init +pixi add mystmd +pixi run myst start +``` +::: + + #### Create a new empty GitHub repository In the GitHub UI, click the `+` icon at the top-right. Select "New repository". @@ -211,10 +261,7 @@ Select your username as the owner, and enter `myst-exercise` as the repository n Leave everything else as default, and click "Create repository". -:::{important} ๐Ÿ‘€ You should notice... -:class: simple -:icon: false - +:::{youShouldNotice} ...GitHub shows you a page for your new, empty repository. A "Quick setup" section includes a URL you can copy. @@ -237,16 +284,15 @@ cd git clone ``` -:::{important} ๐Ÿ‘€ You should notice... -:class: simple -:icon: false - -This command produces the following output: +:::{youShouldNotice} +...this command produces the following output: ``` Cloning into 'myst-exercise'... warning: You appear to have cloned an empty repository. ``` + +The warning is normal! ::: @@ -279,6 +325,8 @@ code block): ```{code} markdown :filename: index.md +# My document title + Hello, world! $$ @@ -289,14 +337,11 @@ $$ The `$$` symbols delimit a math equation, and you can write any $ \LaTeX $ within. -#### Build your site +#### ๐Ÿงช Build your site Right-click the `myst.yml` file in the file browser, and select "Build MyST Project". -:::{important} ๐Ÿ‘€ You should notice... -:class: simple -:icon: false - +:::{youShouldNotice} ...like last time, a new browser tab opens showing a loading spinner while your site builds. @@ -308,7 +353,7 @@ At the top-right, there is a "Rebuild" button. ::: -#### Try some other MyST features and rebuild +#### Try some other MyST features :::{important} **Keep the tab displaying your website open!** @@ -332,10 +377,13 @@ MyST offers many useful features for technical publishing, including Try out some of these features in your MyST site. + +#### ๐Ÿงช Rebuild your site + **Each time you make changes, rebuild the site by clicking "Rebuild" at the top-right of the site.** -Make changes, rebuild, and view the result as many time as you need! +Make changes, rebuild, and view the result as many time as you want! #### Give your site a title @@ -348,6 +396,7 @@ Your config file should now look like this: ```{code} yaml :filename: myst.yml +:linenos: :emphasize-lines: 5 # See docs at: https://mystmd.org/guide/frontmatter @@ -367,12 +416,11 @@ site: # logo: site_logo.png ``` -**Save and rebuild your site.** +#### ๐Ÿงช Rebuild your site -:::{important} ๐Ÿ‘€ You should notice... -:class: simple -:icon: false +Save and rebuild your site. +:::{youShouldNotice} ...the text near the top-left of your site now says "My site" (or whatever you chose for your title) instead of "index". @@ -396,7 +444,8 @@ Your config file should now look like this: ```{code} yaml :filename: myst.yml -:emphasize-lines: 14 +:linenos: +:emphasize-lines: 13-14 # See docs at: https://mystmd.org/guide/frontmatter version: 1 @@ -416,16 +465,18 @@ site: # logo: site_logo.png ``` -**Save and rebuild your site.** +#### ๐Ÿงช Rebuild your site -:::{important} ๐Ÿ‘€ You should notice... -:class: simple -:icon: false +Save and rebuild your site. +:::{youShouldNotice} ...the text near at the very top-left of your site now says "My logo text" (or whatever you chose for your logo text) instead of "Made with MyST". ::: +:::{gitCommitCheckpoint} Initialize MyST site +::: + #### ๐Ÿง  What do we know now? @@ -440,48 +491,577 @@ chose for your logo text) instead of "Made with MyST". ## Building a PDF with MyST -TODO +MyST enables building a PDF from the same source as you built your website. + +Some features are web-specific, however, and won't be rendered in an output PDF. + +Let's try it out! ### ๐Ÿ’ช Exercise C: Render a PDF from the same source as your website -TODO +#### Attempt to build our current project as PDF + +Building PDF(s) from a MyST project requires one command in the terminal: + +```bash +myst build --pdf +``` + +:::{youShouldNotice} +...this command fails with: + +``` +๐Ÿ“ญ No file exports with kind "pdf" found. +You may need to add an 'exports' field to the frontmatter of the file(s) you wish to +export: + +--- +exports: +- format: pdf +--- +``` + +This is because we need to tell MyST which pieces of the site should be exportable as +PDF. +::: + + +#### Configure the frontmatter to allow PDF export + +To tell MyST that we want a PDF export for a specific document, we need to define {term}`frontmatter`. + +While we're here, let's also set some other metadata like the document's author. + +Add to the top of `index.md`: + +```{code} markdown +:filename: index.md +:linenos: +:emphasize-lines: 1-14 + +--- +authors: + - name: "Your name" + affiliations: + - "Your employer" + email: "your-email@example.com" + github: "your-github-username" + # Optional: Do you have an ORCID? + # orcid: "0000-0000-0000-0000" +export: + - format: "typst" + template: "plain_typst_book" + output: "paper.pdf" +--- + +# My document title + +Hello, world! +``` + +:::{hint} On quoting in YAML, a rant +:class: dropdown + +YAML is intended to be a human-friendly data format. +There are many ways that it excels at this goal, and in other ways, it introduces +pitfalls that are easy to fall in to. + +A single rule will help you avoid many of these pitfalls: +**_always quote strings in your YAML_**. + +**Example: Upgrading the Python version** + +```yaml +requires_python: 3.9 +``` + +โ˜๏ธ +Looks good to me, and it works fine. I'll just upgrade that to 3.10... + +```yaml +requires_python: 3.10 +``` + +๐Ÿ™… +This value isn't a string, it's a number, so it evaluates to 3.1. + +```yaml +requires_python: "3.10" +``` + +โœ… +The only way to get the result you want is to quote the string. + +**Example: ISO country codes** + +```yaml +country_code: gb +``` + +โ˜๏ธ +Looks good to me, and it works fine. I'll just update my program to process data for +Norway... + +```yaml +country_code: no +``` + +๐Ÿ™… +This value isn't a string, it's a **boolean**, so it evaluates to `false`. + +```yaml +country_code: "no" +``` + +โœ… +The only way to get the result you want is to quote the string. + +Save yourself the pain: +**_always defensively quote your YAML strings_**. + +There are many more ways YAML can be confusing. +There are a lot of special rules to remember! +For more, check out +[The YAML document from hell](https://ruudvanasseldonk.com/2023/01/11/the-yaml-document-from-hell) +and . +::: + + +#### ๐Ÿงช Build the PDF + +To build the PDF, try `myst build --pdf` again. + +:::{youShouldNotice} +...this command produces the following output at the end: + +``` +๐Ÿ–จ Rendering typst pdf to paper.pdf +``` +::: + +Try opening the PDF! +Double-click `paper.pdf` in the JupyterLab file browser. + +:::{youShouldNotice} +...the content is fairly simple. +There is a title page, a blank table of contents, and then your content on the 3rd page. +::: + +:::{gitCommitCheckpoint} Add PDF export +::: + +:::{note} Other PDF templates +:class: dropdown + +This document was rendered with the `"plain_typst_book"` template. +Other PDF template options are available! + +Try running `myst templates list --typst` to see a list of available templates. + +More information is available on the +[official MyST PDF-building documentation](https://mystmd.org/guide/creating-pdf-documents). +::: + #### ๐Ÿง  What do we know now? -TODO +* MyST documents can be built to multiple output formats, including PDFs. +* Frontmatter is YAML metadata on a Markdown document that can tell MyST which documents + should be built as PDF. +* [Typst](https://typst.app/) can be used as an alternative document engine to + $ \LaTeX $ for rendering PDFs by specifying `export.format: "typst"` in the frontmatter. +* If you opened the collapsed section on quoting YAML, you know the author of this + document has been burned too many times. **Quote your strings**! ๐Ÿ˜ ## Hosting your website for free -### GitHub Pages +There are many platforms for hosting a website (and PDF!) for free. +We'll discuss some common options for open source projects. + + +### [GitHub Pages](https://docs.github.com/en/pages) + +GitHub Pages is, as it sounds, a GitHub-native solution for hosting web pages. +It doesn't offer any advanced features, it only enables building a website from a GitHub +repository. + +Pages are built using [GitHub Actions](https://github.com/features/actions). + + +### [ReadTheDocs](https://about.readthedocs.com/) + +ReadTheDocs is a community service for building and hosting webpages, most commonly +software documentation. +It provides advanced functionality like website previews for Pull Requests, +multi-language builds, and multi-version builds. + +It uses +[its own unique file format](https://docs.readthedocs.com/platform/stable/config-file/v2.html) +for specifying build processes. + + +### ๐Ÿ’ช Exercise D: Publish your paper and website to GitHub Pages + +We're going to use GitHub Pages because it's more straightforward to configure. +We recommend trying out ReadTheDocs if you need more advanced features! -TODO +#### Update repository's GitHub Pages settings -### ReadTheDocs +* Open your repository URL in your browser +* Click the "Settings" tab towards the top +* Select "Pages" from the left menu +* Change the "Source" dropdown to "GitHub Actions" -TODO +#### Add GitHub Actions configuration file -### ๐Ÿ’ช Exercise D: Publish your paper and website to GitHub +Now that we've set up our repository to build our website using GitHub Actions, +we need to define the build process in a configuration file. + +MyST can do this automatically! +In the terminal, from your `myst-exercise` project directory: + +```bash +myst init --gh-pages +``` + +:::{youShouldNotice} +...this created a new file (and its parent directories) at +`.github/workflows/deploy.yml`. + +**You may need to show hidden files so you can see the `.github` directory in the file +browser. +Select View > Show hidden files** from the menu. +::: + +:::{gitCommitCheckpoint} Set up publish with GitHub Actions +::: + + +#### ๐Ÿงช View the action results + +After committing and pushing the GitHub Actions configuration file in the previous step, +we can view the build that was triggered. + +Visit your repository URL in GitHub. +Click the "Actions" tab at the top. + +:::{youShouldNotice} +...there is 1 workflow run listed, ideally with a green checkmark. +::: + +Click on the workflow run shown on this page. +If it succeeded, you should see a node named "deploy" displayed on the page: + +![](./github-actions-deploy-successful.jpg) + +Click the link in the "deploy" node to view your built website. + +:::{youShouldNotice} +...your webpage displays on the public Internet! + +At the top-right of this page, there's a "download" icon that looks a bit like this: + +๐Ÿ“ฅ + +When you click that icon, you're presented with an option to download your document as a +PDF. + +When you download your PDF, it looks exactly like the PDF you built manually earlier! +::: + +If your deploy failed, click the "deploy" node to view the error logs. +See if you can solve the error on your own, and let an instructor know if you need help! + + +#### Display your GitHub Pages URL on your repository homepage + +GitHub offers a convenience feature to enable you to view your GitHub Pages URL on the +homepage of your GitHub repo. + +Visit the URL for your GitHub repo homepage. +Towards the top-right, click the cog/gear icon (โš™๏ธ). + +![](./github-repo-about-cog.jpg) + +Finally, check the "Use your GitHub Pages website" checkbox, and then click "Save +changes". + +:::{youShouldNotice} +...your GitHub Pages URL is visible near the cog/gear icon. +Click the link to immediately open your website. +::: -TODO #### ๐Ÿง  What do we know now? -TODO +* GitHub repositories need some initial setup in the web interface to publish a MyST + site built in GitHub Actions. +* MyST can do most of the work of configuring GitHub Actions deployments for us with a + single command: `myst init --gh-pages`. +* We can see deployment progress and results in the GitHub repository's "Actions" tab. +* MyST will automatically build PDFs when building a website, and generate a download + link on the relevant page. +* A GitHub repository can display a convenient link to the related GitHub Pages website. ## Getting a DOI -TODO +A {term}`DOI` can uniquely identify and track your research products, enabling easy +citing and tracking of citations. +DOIs can even be versioned, enabling citations to reference a research product at a +specific point in time. + +DOIs can be associated with your unique academic identity through the use of +an {term}`ORCID`. + +:::{important} +A DOI and ORCID can help defend your work against {term}`scooping` by providing +verifiable {term}`provenance` for your work, making it clear that your work came first. + +They can also enable credit for the work to be more equitably distributed by crediting +all forms of contributions. +::: + +We can automate the production of DOIs with GitHub and [Zenodo](https://zenodo.org/) (a +**free** DOI registrar developed and operated by [CERN](https://home.cern/)). ### ๐Ÿ’ช Exercise E: Get a DOI for your published content on GitHub -TODO +#### Create an ORCID + +Visit the [ORCID registration page](https://orcid.org/register) and create an account. + +Enter your **personal email** as your primary email. +Be sure to also enter your institutional email as an additional email. +You can more emails after you register. + + +#### Sign up for Zenodo + +Visit the [Zenodo signup page](https://zenodo.org/signup/) and sign up with either your +GitHub account or ORCID. +We recommend using GitHub, as you'll need to link your GitHub account either way. + + +##### Link your GitHub account + +If you didn't signup with GitHub, you'll need to link your GitHub account. + +After you've signed in, click the username dropdown at the top-right of the Zenodo +interface. + +On the left panel, select "Linked accounts". + +On the GitHub row, click "Connect". +You may be prompted to log in, then you'll be prompted to accept some dialogs. + +:::{youShouldNotice} +Back in the Zenodo "Linked accounts" screen, a green checkmark will be +displayed next to GitHub. +::: + + +#### Enable auto-DOI for your repository on Zenodo + +After you've signed in to Zenodo, click the username dropdown at the top-right of the +Zenodo interface. + +On the left panel, select "GitHub". + +:::{youShouldNotice} +...there is a large "Get started" display with a 3-step process you can follow to enable auto-DOI for a +repository. + +At the top right of this "Get started" box, there is a "Sync now" button. +::: + +Click "Sync now". +It may take a moment to complete the sync. + +:::{hint} Help, I received a `504` error! +:class: dropdown + +If you receive a `504` error, +[this is common for users with large numbers of public repositories](https://github.com/zenodo/zenodo-rdm/issues/1118). +Wait a few minutes and refresh the page; eventually your repository list will be updated +::: + +Find your repository in the list and flip the switch for that repository +to "ON". + +![](./zenodo-repository-enable.jpg) + + +#### Create `CITATION.cff` + +A `CITATION.cff` file is the project metadata that enables Zenodo to populate a DOI. + +MyST can generate a `CITATION.cff` for you! +But it needs to be told which documents to use to populate this metadata. + +Edit `index.md` to add another export format of `"cff"`: + +```{code} markdown +:filename: index.md +:linenos: +:emphasize-lines: 14 + +--- +authors: + - name: "Matt Fisher" + affiliations: + - "Schmidt Center for Data Science & Environment" + - "University of California, Berkeley" + email: "matt.fisher@berkeley.edu" + github: "mfisher87" + orcid: "0000-0003-3260-5445" +export: + - format: "typst" + template: "plain_typst_book" + output: "paper.pdf" + - format: "cff" +--- + +# My document title +``` + +Now we can build our `CITATION.cff` file with the command: + +```bash +myst build --cff +``` + +:::{youShouldNotice} +...the following output: + +``` +๐Ÿ“‘ Exported CFF in 37 ms, copying to CITATION.cff +``` +::: + +:::{gitCommitCheckpoint} Add CITATION.cff for Zenodo DOI +::: + +As your project grows and changes, you can regenerate this file by repeating +that command. + +You can also edit your citation file by hand -- it's in the YAML format, which may be +familiar to you now! +Check out the +[full CFF specification](https://citation-file-format.github.io/assets/pdf/cff-specifications-1.0.0.pdf) +to see what kind of information you can populate! + + +#### Create a GitHub release + +Zenodo creates DOIs **only** when you create releases in GitHub. + +Visit the URL for your GitHub repository's homepage. + +Click the "Create a new release" button on the right sidebar. + +![](./github-create-a-release.jpg) + +Click the "Tag" dropdown and click "Create new tag". +We'll use tags to create an ascending numerical sequence for our releases. +For simplicity, let's enter the date in `YYYY.MM.DD` format, e.g. `2025.12.18`. + +:::{hint} Versioning schemes +:class: dropdown + +There are many +[versioning schemes](https://nesbitt.io/2024/06/24/from-zerover-to-semver-a-comprehensive-list-of-versioning-schemes-in-open-source.html) +to choose from. +The one we suggested above is called ["CalVer"](https://calver.org/) or "calendar versioning". + +You may want to try an extremely common versioning scheme called +["SemVer"](https://semver.org/) or "semantic versioning" enables embedding +information about the implications of upgrading to any given version in the +version number itself. +::: + +Give your release the title "Initial release". + +You don't need to enter anything in the "Release notes" field, but we recommend +using the "Generate release notes" button as a starting place. + +:::{hint} "Generate release notes" only generates one line of text! +:class: dropdown + +This feature uses +[GitHub Pull Requests (PRs)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) +to generate a list of changes. +If you don't use PRs, you will only see a "Changelog" link, this is normal. +::: + +Finally, **click "Publish release"**. + +Zenodo will automatically generate your DOI now. + + +#### Add a badge to your README + +Zenodo also automatically generates a beautiful DOI "badge" you can display on +your repository's README or anywhere else on the web. + +To use the badge, click the username dropdown at the top-right of the Zenodo +interface, and select "GitHub". + +Locate your repository on the list of enabled repositories and click on the +blue DOI badge: + +![](./zenodo-doi-badge.jpg) + +Copy the "Markdown" code and paste it into a new `README.md` file in your repository: + +```{code} markdown +:filename: README.md +:linenos: +:emphasize-lines: 1 + +[![DOI](https://zenodo.org/badge/1100194185.svg)](https://doi.org/10.5281/zenodo.17716242) + +# My exercise from the AGU workshop "Open Source Geospatial Workflows in the Cloud" +``` + +:::{youShouldNotice} +...your repository homepage renders your `README.md` file with a pretty blue badge at the top ๐Ÿคฉ + +Clicking the badge takes you to the Zenodo homepage for your DOI. +From here, you can generate citations in a variety of formats or download your archived repository as a Zip file. +::: + +:::{hint} Writing a useful README +:class: dropdown + +The README is the first thing that a user sees when they interact with your repository. + +Check out +[The Turing Way's README guide](https://book.the-turing-way.org/project-design/pd-overview/project-repo/project-repo-readme/) +for some thoughts that may help you make your README more useful. +::: #### ๐Ÿง  What do we know now? -TODO +* An {term}`ORCID` uniquely identifies ourselves +* A {term}`DOI` uniquely identifies our publication +* A DOI can be associated with an ORCID +* A DOI can help protect us against scooping and more accurately and fairly reflect all + contributions to the work +* Zenodo can "auto-DOI" a GitHub repository + * DOIs are automatically generated from GitHub Releases + * DOIs can be updated over time with changes by creating new GitHub Releases +* We can display our DOI in GitHub with Markdown in our README + + +## ๐ŸŽ‰ Congratulations, you're done! + +Great job finishing this module. +If you'd like continued support in applying these skills to your work, please join the +[MyST community on Discord](https://discord.mystmd.org/) and/or ask questions in the +[CryoCloud Slack](https://book.cryointhecloud.com/index-3#slack-account)! diff --git a/modules/05-sharing-and-publishing/zenodo-doi-badge.jpg b/modules/05-sharing-and-publishing/zenodo-doi-badge.jpg new file mode 100644 index 0000000..3c44c9c Binary files /dev/null and b/modules/05-sharing-and-publishing/zenodo-doi-badge.jpg differ diff --git a/modules/05-sharing-and-publishing/zenodo-repository-enable.jpg b/modules/05-sharing-and-publishing/zenodo-repository-enable.jpg new file mode 100644 index 0000000..9a69959 Binary files /dev/null and b/modules/05-sharing-and-publishing/zenodo-repository-enable.jpg differ diff --git a/myst.yml b/myst.yml index e1a2725..6e2a459 100644 --- a/myst.yml +++ b/myst.yml @@ -7,6 +7,11 @@ project: # authors: [] license: "MIT" github: "https://github.com/geojupyter/workshop-open-source-geospatial" + plugins: + - "plugin-custom-directives.mjs" + error_rules: + - rule: "doi-link-valid" + severity: "warn" exclude: - "_*" - "README.md" diff --git a/plugin-custom-directives.mjs b/plugin-custom-directives.mjs new file mode 100644 index 0000000..4e7df5b --- /dev/null +++ b/plugin-custom-directives.mjs @@ -0,0 +1,92 @@ +const gitCommitDirective = { + name: 'gitCommitCheckpoint', + doc: 'Renders a consistent callout when the learner should do a Git commit.', + arg: { + type: String, + doc: 'Commit message', + }, + run(data) { + return [{ + type: 'admonition', + kind: 'important', + icon: false, + children: [ + { + type: 'admonitionTitle', + children: [{ + type: 'text', + value: '๐Ÿ’พ Commit & push to GitHub', + }], + }, + { + type: 'code', + lang: 'bash', + value: `git add .\ngit commit -m '${data.arg}'\ngit push -u origin main`, + }, + ], + }]; + }, +}; + +const youShouldNoticeDirective = { + name: 'youShouldNotice', + doc: 'Renders a consistent callout when the learner should notice something.', + body: {type: 'myst'}, + run(data) { + return [{ + type: 'admonition', + kind: 'important', + icon: false, + class: 'simple', + children: [ + { + type: 'admonitionTitle', + children: [{ + type: 'text', + value: '๐Ÿ‘€ You should notice...', + }], + }, + ...data.body, + ], + }]; + }, +}; + +const mystDemoStatic = { + name: 'myst:static', + doc: 'A static/pre-rendered version of the `{myst}` directive which supports plugins.', + body: {type: 'myst'}, + run(data) { + return [ + { + type: "div", + class: "myst-static-input-wrapper", + children: [{ + type: "div", + class: "myst-static-content", + children: [{ + type: "code", + language: "text", + value: data.node.value, + }], + }], + }, + { + type: "div", + class: "myst-static-output-wrapper", + children: [{ + type: "div", + class: "myst-static-content", + children: data.body, + }], + }, + ]; + }, +}; + +const plugin = { + name: 'Our custom functionality', + doc: 'Custom functionality for this workshop website', + directives: [gitCommitDirective, youShouldNoticeDirective, mystDemoStatic], +} +export default plugin; diff --git a/reference/00-vocabulary.md b/reference/00-vocabulary.md index 10955df..312dee9 100644 --- a/reference/00-vocabulary.md +++ b/reference/00-vocabulary.md @@ -1,8 +1,42 @@ # ๐Ÿ” Vocabulary :::{glossary} -Some term -: Some definition -::: +DOI +: A "Digital Object Identifier" is a string of characters (e.g. + ) that uniquely identifies an object (_any_ + object: physical, digital, or conceptual). + [Read more on the official DOI website](https://www.doi.org/the-identifier/what-is-a-doi/). + + +Frontmatter +: A way of embedding metadata with [YAML](https://yaml.org/) at the front (top) of a + document. + Frontmatter can be embedded at the top of a Markdown document or in the first Markdown + cell of a Jupyter Notebook. + [Read more in the official MyST frontmatter docs](https://mystmd.org/guide/frontmatter). + +Open science +: A movement to make research products (papers, data, software) and processes accessible + to everyone. + A more stringent interpretation of open science involves enabling not just access, but + collaboration, throughout the scientific process, not just at the end. + [Read more on Wikipedia](https://en.wikipedia.org/wiki/Open_science). -Reference to {term}`Some term `. +ORCID +: An "Open Researcher and Contributor ID" that uniquely identifies an academic + contributor and enables tracking and associating their identity with {term}`DOIs `. + [Read more on the official ORCID website](https://info.orcid.org/what-is-orcid/). + +Provenance +: The history or chronology of a thing. + The provenance of your research products can be established and verified by publishing + the source code and creating {term}`DOIs `. + +Scooping +: Being "beaten to the punch" or left in second place in the attempt to publish research + or a discovery. + This term is often used as a counter-argument for {term}`open science` by implying that + sharing your work openly will result in plagiarism. + For more, please read + [Afraid of Scooping โ€“ Case Study on Researcher Strategies against Fear of Scooping in the Context of Open Science](https://doi.org/10.5334/dsj-2017-029). +:::