Getting Started with Developer Notes

Overview¶

This guide will introduce you to Developer Notes (DevNotes) as a way to quickly share ideas and results with the developer community. This guide assumes that you have familiarized yourself with Nucleus Hub, see Getting Started with Nucleus Hub for more information.

Configuring Curvenote API Key¶

Most of the DevNote tools that appear in the Launcher require setting up API access to Curvenote to work as expected. API access can be set up by following these steps:

• Navigate to the Curvenote website and create an account.

• Create a new blank project and click ‘NEXT’

• Go to personal settings.

• Select ‘API Access’ and click ‘Generate New Token’.

  • Give the token a useful description and select Expiry for the maximum time allowed.

• From Nucleus Hub, open a terminal window from the Launcher and run the command curvenote token set [my-token]

• You should see a message that says: Token set for "[curvenote-username]" <curvenote-email-account> at https://api.curvenote.com/login

Curvenote Login

Curvenote Personal Settings

Create DevNote¶

A new DevNote project can be created in Nucleus Hub from the Launcher. The new project will appear in your devnotes/ directory. This workflow is pulling in our DevNote project template from GitHub into Nucleus Hub. Follow these steps to create a new project:

• Create a new DevNote project

  • Select Create from the row of Nucleus tools on the Launcher.

  • You will be prompted for some basic information to initialize your project:

    • “Enter a directory name for your project” -> This is the name of the subdirectory in which your new project will appear, e.g. devnotes/my-project

    • “Add author(s)” -> You can safely skip this step and fill in author information later; however, the most efficient way would be to initialize the project using your ORCID.

    • “Would you like to start a local server now?” -> This step is unnecessary, press n

  • Find your new DevNote project by using the file browser to navigate to devnotes/my-project

  • Check to see if your author information was entered correctly by inspecting the file curvenote.yml.

To learn more about the filestructure and component files in a typical DevNote project, please refer to the Docs page Parts of a Developer Note.

Notes

• You must be in the directory of the project you want to preview.

• This tool can be used in any directory, not just devnotes.

• The first time you preview a project may take 10-20 seconds before showing a preview.

Troubleshooting: No known issues.

Live Preview¶

DevNotes are written using MyST Markdown, a flavor of Markdown design for technical and scientific communication. DevNotes are built from Markdown (.md) and Jupyter Notebook (.ipynb) files. The built DevNotes can be inspected in live-preview mode. The following describes how to preview DevNotes in Nucleus Hub:

• Preview your DevNote.

  • Use the file browser to navigate to the DevNote directory devnotes/my-project.

  • Open the file main.md in your directory.

  • Open a new Launcher window by clicking the “+” at the top of the screen.

  • Click the button “Preview” in the “Developer Notes” toolbar of the Launcher window. Note: you must be in devnotes/my-project directory.

  • You may see an error message. That’s ok.

  • Create a split screen by dragging the “Preview” tab to the right corner of the screen.

  • Make an edit, say to the level 1 heading, e.g. #Background - edited. The preview window should automatically refresh and you should now be able to preview any updates to your DevNote in realtime.

Notes

• You must be in the directory of the project you want to preview.

• This tool can be used in any directory, not just devnotes.

• The first time you preview a project may take 10-20 seconds before showing a preview.

Troubleshooting

• The live-preview is no longer synced to my edits:

  • Refresh the window by right clicking and selecting “Reload Frame” from the context menu (this feature is not available on all browsers).

  • If the sync is still lost, this might signal that there is a fatal error in your project that prevents the document from compiling at all.

• There is a fatal error in my DevNote:

Error message

Splitscreen

Draft Submit¶

DevNotes that are visible from the Developer Notes website (https://devnotes.nucleus.engineering/) are hosted on a deployment server. Some features of your DevNote may not be accurately represented by using the Preview tool alone. The Draft Submit tool allows you to preview your DevNote exactly as it will appear when hosted on the deployment server and viewed from the Developer Notes website.

When your DevNote is ready for submission, you can preview how it will look on the Developer Notes site:

• Draft submit to deployment server.

  • While you’re in the devnotes/my-project directory, click the button “Draft Submit” in the “Developer Notes” toolbar of the Launcher window.

  • Click the URL link at the end of the terminal output.

Notes

• Specific things to keep in mind when inspecting your draft include:

  • Properly formatted thumbnail image.

  • Functional cross-referenced Jupyter cells.

  • All attachments and files are included.

Troubleshooting: No known issues.

Submit¶

If things look good after inspecting your DevNote using “Draft Submit”, you can submit your draft to be posted by using the Publish tool. This will send the DevNote to the Nucleus Core development team.

• Submit DevNote

  • While you’re in the devnotes/template directory, click the button “Publish” in the “Developer Notes” toolbar of the Launcher window.

  • Someone from the Nucleus Core development team will be in touch with you soon.

Notes: None.

Troubleshooting: No known issues.