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

[Draft] Add Github action for autogenerating table of contents json files #3133

Draft
wants to merge 26 commits into
base: main
Choose a base branch
from

Conversation

Blargian
Copy link
Member

@Blargian Blargian commented Jan 23, 2025

Summary

Adds a Github action for generating table of contents .json files. These will be used to automatically generate table of contents tables on the landing pages.

Updates the current script to be able to:

  • accept arg --dir
  • generate one table of contents file for all files in a folder and it's subfolders (eg - as we would need for interfaces/formats with arg --single-toc)
  • generate one table of contents per folder (the usual use case, default)

Future improvements:

  • Extend the script to be able to accept a single file which will list directories to generate for and whether to do a single toc or one per subdirectory. eg:
/en/cloud/manage
/en/interfaces/formats --single-toc

Our folder structure's aren't great so for the time being we will add folders one by one.

Checklist

@Blargian Blargian changed the title [Draft] Add Github action for autogenerating table of contents files [Draft] Add Github action for autogenerating table of contents json files Jan 23, 2025
@Blargian
Copy link
Member Author

Blargian commented Jan 23, 2025

Notes for self:

So, it works - toc.json is generated. This will work for docs on the ClickHouse/clickhouse-docs repo, we can just commit the added files when the workflow runs. However, the problem is that we have any files from the ClickHouse/ClickHouse repo in .gitignore. So the question now is do we make toc.json which is generated in these folders an exception and commit them to this repo? This is problematic I guess as we copy content across during build - they would get overwritten I assume. On the other hand, we wanted to improve that aspect of the build process and use something like rsync (see #3087)

Alternative solutions:

  • copy all table_of_contents files to their own folder maybe named as interfaces_formats_toc.json for example rather than just one toc.json in each folder. I don't like that solution much.
  • have blank toc.json files in the ClickHouse/ClickHouse docs folders and just populate them from the action.

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.

1 participant