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

Recategorize API reference #663

Merged
merged 3 commits into from
Oct 7, 2024
Merged

Conversation

sgillies
Copy link
Collaborator

@sgillies sgillies commented Oct 4, 2024

Previously, our API reference had 8 sections in the main body and sidebar, and every module in the API reference was in exactly one section.

We're reducing the number of sections to 5:

  • Catalog
  • Collaborate
  • Analyze
  • Scale
  • Account

And reorganizing the modules within these new sections like so:

  • Domain-specific modules (SOMA, VCF, etc) are merged into the new "Analyze" category.
  • The previous "Compute", "DAG", and "Utilities" categories are merged into the new "Scale" category.
  • Modules of the previous "Cloud Services" category are distributed to "Catalog", "Collaborate", "Scale", and "Account".
  • There is overlap between the new "Catalog" and "Collaborate" sections. Some API modules are in both. That is because the Cloud-Py API has historically been organized around types of assets (groups, arrays, files, notebooks). The new categories cut across some existing modules.

Important details

  • This PR does not add any new API documentation for modules, it only moves existing documentation to new categories.
  • Placeholder descriptions for categories are used and should be replaced by real, useful text that is aligned with the website.
  • The quartodoc software that we're using for the API reference appears to have some deficiencies. For example, we've put a lot of work into making sure that functions in all vcf submodules are exported from tiledb.cloud.vcf, but quartodoc seems unable to produce API documentation for that high-level module.

Summary

Let's fix any obvious errors in categorization of modules now and then iterate as we progress.

@sgillies sgillies marked this pull request as ready for review October 5, 2024 02:19
docs/_quarto.yaml Outdated Show resolved Hide resolved
docs/_quarto.yaml Outdated Show resolved Hide resolved
docs/_quarto.yaml Outdated Show resolved Hide resolved
docs/_quarto.yaml Outdated Show resolved Hide resolved
docs/_quarto.yaml Outdated Show resolved Hide resolved
Copy link
Contributor

@nickvigilante nickvigilante left a comment

Choose a reason for hiding this comment

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

Great work!

docs/_quarto.yaml Show resolved Hide resolved
docs/_quarto.yaml Outdated Show resolved Hide resolved
@sgillies
Copy link
Collaborator Author

sgillies commented Oct 5, 2024

Placeholders are gone, replaced by meaningful text.

@sgillies sgillies merged commit 3b957a7 into main Oct 7, 2024
18 checks passed
@sgillies sgillies deleted the sg/sc-56843/api-reference-reorg branch October 7, 2024 14:01
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.

3 participants