[GEN-1109] Setup base mkdocs for genie

rxu17 commented 4 months ago

Purpose: This draft PR adds an auto-documentation tool mkdocs and mkdocstrings for the Genie repo, setting up the initial skeleton and base pages for the genie docs. It helps auto-document our codebase as well as allowing us to add custom markdown pages.

This PR is just meant to set up the skeleton of the docs so we can get started with documenting our codebase and looking into areas of lacking documentation / improvement, refining specific things like font size, headings, etc will be done in a separate ticket.

Limitations: We will not be able to auto-document our R scripts as there isn't an extension similar to mkdocstrings for R. We can use a mix of roxygen2 and knitr to convert our R code to Rmarkdown files -> markdown files which can then be rendered in mkdocs. However this way is more hacky. We plan to convert all our R scripts to Python eventually / move the dashboard R scripts to Nextflow module so this may not be a concern.

Changes: Initial vision and structure for the genie docs:

/project-root
├── Home
├── Getting Started
├── Tutorials
├── Reference (this page contains all the technical references to our pipeline code (all the modules and functions)
│   ├── Pipeline Commands (contains the scripts that have the command args to run the pipeline steps)
│   ├── Main Pipeline Steps
│    │    ├── Input to Database (include all scripts unique to validation / processing like input_to_database, validation, process_mutation, write_invalid_reasons)
│    │    ├── Database to Staging (include all scripts unique to consortium release like database_to_staging.py)
│    │    ├── Consortium To Public (include all scripts unique to public release like consortium_to_public.py)
│   ├── Fileformats (all of our fileformats including base fileformat class)
│   ├── Helper Modules (all of the helper tools used across the pipeline - extract, load, transform, process_functions)

Testing: In the root directory run mkdocs serve to view the live docs

Examples:

thomasyu888 commented 4 months ago

Thanks @rxu17 for your work here! I agree that we don't have to worry about auto generating the R code documentation for now. It'd be great if this was linked to github pages!

rxu17 commented 4 months ago

You can see the live site at: https://sage-bionetworks.github.io/Genie/