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

Redo reference #162

Merged
merged 8 commits into from
Jun 23, 2023
Merged

Redo reference #162

merged 8 commits into from
Jun 23, 2023

Conversation

ianspektor
Copy link
Collaborator

@ianspektor ianspektor commented Jun 19, 2023

New docs structure

Docs now work as follows:

  • The structure that the navigation follows is the structure of markdown files under docs/src/reference
  • If a file there has content, the code ref generator doesn't touch it. Keep in mind you can still use mkdocstring identifiers (e.g. ::: temporian.to_csv) for them to be auto-filled with that symbols' docstring. More info here.
  • If the file is empty, it is interpreted as a placeholder for the top-level symbol with its same name and its reference page is generated in its same path. E.g., if an empty docs/src/reference/temporian/io/to_csv.md file exists, the reference page for temporian.to_csv will be generated under reference/temporian/io/to_csv/ in the docs.

Tests

Added two tests:

  • One that checks that the symbols available in temporian. are exactly the ones we expect
  • One that checks that all of those symbols have an auto-generated page in the reference folder (so that we don't forget adding it when adding a new symbol)

Bonus

  • Managed to remove the tp.core, tp.implementation, etc. symbols by simply doing del core in the init file 👀
  • Ordered the symbols in the left nav alphabetically + folders at the bottom

Copy link
Collaborator

@DonBraulio DonBraulio left a comment

Choose a reason for hiding this comment

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

This reference is ✨✨✨

temporian/test/public_api_test.py Show resolved Hide resolved
temporian/test/public_api_test.py Show resolved Hide resolved
docs/gen_ref_pages.py Outdated Show resolved Hide resolved
docs/gen_ref_pages.py Show resolved Hide resolved
@ianspektor ianspektor merged commit 353c767 into main Jun 23, 2023
@ianspektor ianspektor deleted the redo-reference branch June 23, 2023 13:38
Copy link
Collaborator

@achoum achoum left a comment

Choose a reason for hiding this comment

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

LGTM

@@ -1,111 +1,58 @@
"""
Generate the code reference pages.
Copy link
Collaborator

Choose a reason for hiding this comment

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

What about adding a comment that tell that this script is executed when running mkdocs serve -f docs/mkdocs.yml?

@@ -18,7 +18,7 @@ Check the index on the left for a more detailed description of any symbol.
| ----------------------------------------- | -------------------------------------------------------------------------------------- |
Copy link
Collaborator

Choose a reason for hiding this comment

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

This front page is now awesome.

docs/gen_ref_pages.py Show resolved Hide resolved
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