Restructure docs incorporating info from VEDA wiki

stephenkilbourn commented 2 months ago

This is work in response to #169

We have the VEDA wiki and these veda-docs. I've taken a pass at comparing what info was different in the two documentation sources.

The main changes I made:

Inserted a 2 column "table" section on the index page.
Renamed "Services" to "Components" to match the wiki. I also added the Analytics and a Data Services page
Updated the sidebar to match

TODO: add pages for missing links on new index page tables

github-actions[bot] commented 2 months ago

PR Preview Action v1.4.8 :---: :rocket: Deployed preview to https://NASA-IMPACT.github.io/veda-docs/pr-preview/pr-170/ on branch gh-pages at 2024-10-25 13:43 UTC

stephenkilbourn commented 2 months ago

@j08lue

I am wondering - why did you move everything under /pages?

The logic was more from a developer experience perspective: Especially as I started stubbing out the new pages, we had a plethora of .qmd files in the root (currently, 9 plus the index.qmd), along with directories for some sections. Having a logical grouping felt easier to locate and maintain.

stephenkilbourn commented 2 months ago

@j08lue - ok, I did a pass and links are all working in the preview deploy. I can move page files to a flatter hierarchy if that's preferred. I focused on getting the sidebar updated for now. It's now closer in style to the eu-csde layout, i think.

stephenkilbourn commented 2 months ago

These pages are currently "Coming Soon". I'm not finding source material for these. If someone is a SME on the topics, then I can work with them to incorporate details into the pages.

title: "VEDA Access" -- subtitle: "How to access the VEDA ecosystem"
title: "VEDA Architecture" -- subtitle: "VEDA Architecture"
title: "VEDA Community and Support" -- subtitle: "The VEDA Community"
title: "How to Deploy VEDA" -- subtitle: "How to Deploy Your Own VEDA"
title: "VEDA Recommendations For Maintainers" -- subtitle: "VEDA Recommendations For Maintainers"
title: "Related Projects" -- subtitle: "Related Projects"
title: "VEDA Standards" -- subtitle: "VEDA Standards"

smohiudd commented 2 months ago

We currently have API documentation under Components/APIs and under API Docs. I was thinking API Docs would be either direct embed of the swagger docs (like Planetary Computer) or link to swagger docs. Documentation on embedding swagger docs.
I don't think we'll be able to get through all the Todos in your list @stephenkilbourn in this PR. I'm not a big fan of "Coming Soon" pages. For this PR can we commit to including at least the "Software and Services Architecture" and "Repositories" sections to start and create issues for the other sections (and remove the stubs for now)?
For the "Getting Access" section, we can use this existing text from Jupyter Hub. I think that's the only service that requires auth right now. Once we have more details from veda-auth-central about adding users, groups, etc. we could add that info in this section
Can we bring back the TOC sub list of pages for Contributing like the current docs?
I agree with @j08lue about using the root source as the TOC without adding /pages. Is there a setting in Quarto where we can specify a root directory?

stephenkilbourn commented 2 months ago

The above 4 commits should address all 5 points. I left the access section in the JupyterHub page, and just linked to that specific section from the TOC and sidebar. My thought process is that once we get the veda-auth-central info, we can create a unique access page.

smohiudd commented 1 month ago

recommendation for architecture diagram:

include entire system diagram (everything in veda deploy: backend, airflow, auth, features api, grafana, etc.)
high level boxes/icons, not necessarily details for each services (i.e. lambda, rds, vpc)

j08lue commented 1 month ago

I am working on aligning the folder structure with the document hierarchy and fixing up menus and internal links, following this proposal https://github.com/NASA-IMPACT/veda-architecture/issues/459#issuecomment-2333673003

Please avoid larger changes until I am done - and I hope you will like the outcome. 😅

smohiudd commented 1 month ago

Thanks @j08lue! I think we are almost there with this PR after your hierarchy changes. As I mentioned last week, under "VEDA open-source ecosystem" I'm ok with just going with (1) Software and Services Architecture and (2) Repositories in this PR and then including the other sections in another PR as we work through assembling that information. Let me know what you think.

j08lue commented 1 month ago

I finished the document tree and hierarchy restructuring: https://docs.openveda.cloud/pr-preview/pr-170/

I made a lot of changes wrt the initial state of this PR and the organization in the wiki.

Left menu, repo folder structure, and home page overview hierarchy are close, but not 100% identical:

I kept the root /notebooks folder for backwards compatibility (not to break external links to our notebooks).
Contributing docs are under /nasa-veda-platform, but linked at main level in the left menu.

I introduced a new section about scientific computing that hosts JupyterHub related docs now and can also have DPS docs etc. later.

All image and internal cross references should be working.

j08lue commented 4 weeks ago

Good for merging now, IMO, @smohiudd.

smohiudd commented 3 weeks ago

Thanks @j08lue. I just pushed a couple changes suggested by @jerikac. We should be good to merge this now!

NASA-IMPACT / veda-docs

Restructure docs incorporating info from VEDA wiki #170