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

Central API Docs #1041

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Conversation

bschifferer
Copy link
Contributor

No description provided.

@bschifferer bschifferer added the documentation Improvements or additions to documentation label Jul 3, 2023
@github-actions
Copy link

github-actions bot commented Jul 3, 2023

Documentation preview

https://nvidia-merlin.github.io/Merlin/review/pr-1041

Comment on lines 55 to 56
- file: api_overview
title: API Documentation
Copy link
Member

Choose a reason for hiding this comment

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

The docs become a little dense with this all under one TOC item. If you are open to experimenting, consider creating another caption like line 3 with "API Documentation" or "Merlin API" or something along those lines.

Centralizing the API is certainly better than how I left it, but I'm also wondering if adding titles would help the reader choose the correct API rather than browse.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I feel the structure looks easy to follow - it is structured in the way how we would import Classes, functions or modules

merlin.dag
merlin.loader
merlin.io
merlin.models
merlin.schema
merlin.systems
nvtabular

Copy link
Contributor

Choose a reason for hiding this comment

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

It might still be nice to organize the packages into themes or something though, because I suspect this makes the most sense to people who are already familiar with what's in each sub-package (e.g. people on the Merlin team.)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@karlhigley do you have a suggestions? I thought organizing it by import statements is the way a user will search for API documentation?

If I want to know something about ColumnsSelector, I know it is in merlin.schema and I will look there first?

Comment on lines +76 to 92
allowlist_externals =
git
cp
commands =
git clone --depth 1 https://github.com/NVIDIA-Merlin/core.git ./docs/core
cp -r ./docs/core/docs/source/api ./docs/source/api_core/
git clone --depth 1 https://github.com/NVIDIA-Merlin/dataloader.git ./docs/dataloader
cp ./docs/dataloader/docs/source/api.rst ./docs/source/api_dataloader.rst
git clone --depth 1 https://github.com/NVIDIA-Merlin/models.git ./docs/models
cp ./docs/models/docs/source/api.rst ./docs/source/api_models.rst
git clone --depth 1 https://github.com/NVIDIA-Merlin/NVTabular.git ./docs/NVTabular
cp ./docs/NVTabular/docs/source/api.rst ./docs/source/api_nvtabular.rst
git clone --depth 1 https://github.com/NVIDIA-Merlin/systems.git ./docs/systems
cp ./docs/systems/docs/source/api.rst ./docs/source/api_systems.rst
git clone --depth 1 https://github.com/NVIDIA-Merlin/Transformers4Rec.git ./docs/Transformers4Rec
cp -r ./docs/Transformers4Rec/docs/source/api ./docs/source/api_transformers4rec/
python -m sphinx.cmd.build -E -P -b html docs/source docs/build/html
Copy link
Member

Choose a reason for hiding this comment

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

If tox alone can get you what you need, I think I'd just go with that. (And, tbh, it escaped my imagination that tox would make it so simple.)

The only alternative that I'd consider is using one of the containers because the containers already have the tagged source in the container.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I wasn't sure if the documentation is build inside a container - in addition, I want to pull the latest documentation code from every repository

@bschifferer bschifferer changed the title [WIP] Central API Docs Central API Docs Jul 5, 2023
docs/source/toc.yaml Outdated Show resolved Hide resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants