[ENH] Add new "Getting started" docs

surchs commented 6 months ago

Closes #184
Close #187
Closes #142
Closes #181

Changes proposed in this pull request:

added a "getting started" section
- this is purposefully very lightweight and inteded to get someone going quickly
- new content that explains how to use the new deployment recipe. Also big warning to not install graphDB
refactored the former local-node and federation setup guides into two new sections:
- configuration: background section with details on the different configuration options you need to know about.
- Also contains the info on "how to do it by hand if you have to"
- maintenance: contains the sections on how to handle data updates. Added:
- how to upgrade the services
- how to stop and relaunch the services after a config change
nav-section to hold the tool-specific guides. This is mainly so the left hand nav section is a bit easier to process visually.
enabled mkdocs material feature to add "go to next/previous section" links in the footer.

Probably best to review this in the staging deploy because the diff is pretty sizable but text mainly has just moved around.

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

netlify[bot] commented 6 months ago

Deploy Preview for neurobagel-documentation ready!

Name	Link
Latest commit	24278e3c7a98eaf66f320f2d22c27629b7be1f63
Latest deploy log	https://app.netlify.com/sites/neurobagel-documentation/deploys/663bda73c886e5000837c85b
Deploy Preview	https://deploy-preview-189--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.

surchs commented 6 months ago

Alright folks, thanks a lot for the in depth review here - I appreciate the effort. I went through the comments / suggestions and addressed most of them. The purpose of this PR (and the new docs section) to me is really to get a sysadmin from first contact to running stack in as few steps as possible - and to provide additional detail after that to go in depth. As long as we check this box, I think this PR has served its purpose. Some of this will have to go in later issues / PRs.

There were also a couple of change requests that are in scope of the PR, but that I disagree with in the interest of keeping the "getting started" section very action oriented and simple. I added my thoughts inline, but for me it all comes down to making the first contact with a new deploying user as easy, clear, and successful as possible so we can then tell them the details when they are excited. That said, we will continue refining the style with user feedback and make sure we get it right.

Please both take another look at and let me know if there are any final changes needed. Let's wrap this up and spread the good word!

neurobagel / documentation