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

Edited the repo's README #1193

Merged
merged 29 commits into from
Feb 27, 2024
Merged

Edited the repo's README #1193

merged 29 commits into from
Feb 27, 2024

Conversation

benji-glitsos-ga
Copy link
Collaborator

@benji-glitsos-ga benji-glitsos-ga commented Feb 26, 2024

Proposed changes

Preview the README: https://github.com/GeoscienceAustralia/dea-notebooks/tree/feature/update-repo-readme

  • Converted README from Restructured Text to Markdown format
  • Edited entire README
  • Moved the ‘Git workflow’ content out into a wiki article and linked to it: https://github.com/GeoscienceAustralia/dea-notebooks/wiki/Git-workflow
  • Separated the ‘Introduction’ section into two sections: Browse the DEA Knowledge Hub and Use the DEA Sandbox
  • Added more links to the DEA Sandbox than on the current README
  • Fixed one broken link (tags index)
  • Commented out the tags content that is currently not relevant since the tags index isnt yet functional on the new Knowledge Hub.

I’ve spellchecked my work.

Closes issues (optional)

Checklist

(Replace [ ] with [x] to check off)

  • Notebook created using the DEA-notebooks template
  • Remove any unused Python packages from Load packages
  • Remove any unused/empty code cells
  • Remove any guidance cells (e.g. General advice)
  • Ensure that all code cells follow the PEP8 standard for code. The jupyterlab_code_formatter tool can be used to format code cells to a consistent style: select each code cell, then click Edit and then one of the Apply X Formatter options (YAPF or Black are recommended).
  • Include relevant tags in the final notebook cell (refer to the DEA Tags Index, and re-use tags if possible)
  • Clear all outputs, run notebook from start to finish, and save the notebook in the state where all cells have been sequentially evaluated
  • Test notebook on both the NCI and DEA Sandbox (flag if not working as part of PR and ask for help to solve if needed)
  • If applicable, update the Notebook currently compatible with the NCI|DEA Sandbox environment only line below the notebook title to reflect the environments the notebook is compatible with
  • Check for any spelling mistakes using the DEA Sandbox's built-in spellchecker (double click on markdown cells then right-click on pink highlighted words). For example:

sandbox_spellchecker

README.md Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated

## Browse the DEA Knowledge Hub

The Knowledge Hub is where you can easily view the notebooks and read DEA Tools documentation. You can browse the following sections.
Copy link
Member

@robbibt robbibt Feb 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @benji-glitsos-ga, thinking about this some more, I think we might want to change these sections up a little. The list of notebook folder dotpoints below ("Beginners guide" etc) applies more specifically to DEA Notebooks than Knowledge Hub itself. I would change the following:

  1. Move the notebook folder dotpoints up under "Introduction" (and perhaps rename this). So essentially, use the dotpoints to describe the content available in DEA Notebooks itself (rather than the fact that they are also rendered in Knowledge Hub).
  2. Change the notebook folder dotpoint links to relative links that will open directly on the Sandbox and Github
  3. Keep the "Browse the DEA Knowledge Hub" section (which is super important to include here), but update it to include a short paragraph describing the kind of content it provides/how it complements DEA Notebooks - e.g. technical product metadata, DEA user and reference guides, changelog and tech alerts, rendered DEA Tools Python API etc.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It turns out the Sandbox doesn't render Markdown files so therefore, I think not many people will be opening these links from the sandbox. I've used absolute links because this README page will be used on the Knowledge Hub for the near future.

ksnip_20240227-102642

README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
Copy link
Member

@robbibt robbibt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks awesome, thanks for this @benji-glitsos-ga !

@benji-glitsos-ga benji-glitsos-ga merged commit c57629e into develop Feb 27, 2024
1 check passed
@benji-glitsos-ga benji-glitsos-ga deleted the feature/update-repo-readme branch February 27, 2024 02:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants