[REF] Create custom paths for user guide and data model pages, refactor section on `local_nb_nodes.json`

alyssadai commented 1 week ago

Closes #99
Closes #241
Closes #114

Changes proposed in this pull request:

Create dedicated subdirectories (paths) for User Guide pages and Data Model pages:
- neurobagel.org/user_guide/...
- neurobagel.org/data_models/...
Turn overview.md into a section index page for the User Guide section (so now, you can navigate to https://neurobagel.org/user_guide directly)
- For reviewer: we could also do this for the variables.md page under Data Model subdirectory, since that page also kind of acts as an overview page
Rename section called "local_nb_nodes.json" in the "Configuring a node" page to something more informative, and restructure section for readability

Checklist

Please leave checkboxes empty for PR reviewers

[x] PR has an interpretable title with a prefix ([ENH], [FIX], [REF], [TST], [CI], [MNT], [INF]) see our Contributing Guidelines for more info)
[x] PR links to GitHub issue with mention Closes #XXXX
[x] Checks pass

Summary by Sourcery

Refactor documentation structure by creating custom paths for User Guide and Data Model pages, and improve the section on 'local_nb_nodes.json' for clarity.

Enhancements:

Refactor the section on 'local_nb_nodes.json' to improve readability and provide more informative content.

Documentation:

Create dedicated subdirectories for User Guide and Data Model pages to improve navigation and organization.
Turn 'overview.md' into a section index page for the User Guide, allowing direct navigation to the User Guide section.
Rename and restructure the section on 'local_nb_nodes.json' in the 'Configuring a node' page for better clarity and readability.

netlify[bot] commented 1 week ago

Deploy Preview for neurobagel-documentation ready!

Name	Link
Latest commit	ac4c6ccf6949f11f0c89a085c9703df9397e2387
Latest deploy log	https://app.netlify.com/sites/neurobagel-documentation/deploys/673cc7b28a2d2f0008f0c09c
Deploy Preview	https://deploy-preview-242--neurobagel-documentation.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

sourcery-ai[bot] commented 6 days ago

Reviewer's Guide by Sourcery

This PR reorganizes the documentation structure by creating dedicated subdirectories for User Guide and Data Model pages, and improves the readability of the node configuration documentation. The changes primarily involve moving files into new directories and updating internal documentation links to reflect the new structure.

No diagrams generated as the changes look simple and do not need a visual representation.

File-Level Changes

Change	Details	Files
Reorganized documentation structure with dedicated subdirectories	Created user_guide/ directory for user guide related pages Created data_models/ directory for data model related pages Updated navigation structure in mkdocs.yml to reflect new directory structure Fixed all internal documentation links to match new file paths	`mkdocs.yml` `docs/user_guide/` `docs/data_models/`
Improved node configuration documentation	Renamed section from 'local_nb_nodes.json' to 'Configuring node names and URLs for federation' Restructured content for better readability Added JSON example formatting Moved warning about federation API address to a more prominent position	`docs/user_guide/config.md`
Fixed image paths in documentation	Updated relative paths to images to account for new directory structure	`docs/user_guide/annotation_tool.md` `docs/user_guide/getting_started.md`

Assessment against linked issues

Issue	Objective	Addressed
#99	Create a dedicated directory for the Neurobagel user guide documentation	✅
#99	Make user guide directly accessible at neurobagel.org/user-guide	✅
#241	Rename the 'local_nb_nodes.json' section in the documentation to be more informative about node naming	✅

Tips and commands

#### Interacting with Sourcery - **Trigger a new review:** Comment `@sourcery-ai review` on the pull request. - **Continue discussions:** Reply directly to Sourcery's review comments. - **Generate a GitHub issue from a review comment:** Ask Sourcery to create an issue from a review comment by replying to it. - **Generate a pull request title:** Write `@sourcery-ai` anywhere in the pull request title to generate a title at any time. - **Generate a pull request summary:** Write `@sourcery-ai summary` anywhere in the pull request body to generate a PR summary at any time. You can also use this command to specify where the summary should be inserted. #### Customizing Your Experience Access your [dashboard](https://app.sourcery.ai) to: - Enable or disable review features such as the Sourcery-generated pull request summary, the reviewer's guide, and others. - Change the review language. - Add, remove or edit custom review instructions. - Adjust other review settings. #### Getting Help - [Contact our support team](mailto:support@sourcery.ai) for questions or feedback. - Visit our [documentation](https://docs.sourcery.ai) for detailed guides and information. - Keep in touch with the Sourcery team by following us on [X/Twitter](https://x.com/SourceryAI), [LinkedIn](https://www.linkedin.com/company/sourcery-ai/) or [GitHub](https://github.com/sourcery-ai).

neurobagel / documentation