Add test to verify tutorial table of contents

[seanpmorgan]

No description provided.

[gabrieldemarmiesse]

Thank you for the pull request! I'm wondering if it would be possible to generate automatically the docs/tutorials/_toc.yaml. Maybe in the build_docs.py? Since we already run the build_docs.py at each PR, that would ensure the code works. What do you think?

[gabrieldemarmiesse]

Maybe it would be cleaner to have that as a pytest test in tools/testing/check_source_code.py? Or in a separate file in this directory? Then we run everything with pytest in one single Github actions job.

[seanpmorgan]

Good idea, will refactor the test to be in standard testing location.

[seanpmorgan]

Thank you for the pull request! I'm wondering if it would be possible to generate automatically the docs/tutorials/_toc.yaml. Maybe in the build_docs.py? Since we already run the build_docs.py at each PR, that would ensure the code works. What do you think?

@MarkDaoust @lamberta Wanted to clarify how the docs team pulls the tutorials into the website. It looks as though build_docs.py generates all API docs and outputs them into a tmp directory. I didn't see any code or flag to copy in the tutorial folder so is it correct that the tutorials are not gathered from running build_docs.py?

We'd like to automate the generation of the tutorial TOC, but need to know where we can insert that so that docs team will pick it up.

[lamberta]

I like the idea of verifying a tutorials entry in the _toc.yaml file using GitHub Actions CI---this could be useful to many TensorFlow projects.

As far as auto-generating the _toc.yaml file, my concern is the title. The page title can be longer and a bit more descriptive (for users and SEO), but leftnav width is limited and nav entries look bad when they spill over multiple lines. You could store a different nav-title somewhere, but that seems unnecessary if you're already verifying the TOC is up-to-date in the CI.

@MarkDaoust can confirm, but I believe build_docs.py is run when importing the "API rule",, which is usually always run at the same times as the "narrative rule", but doesn't have to be. I do not know if we provide a hook when the narrative docs are imported, but maybe that's an option.

[MarkDaoust]

We'd like to automate the generation of the tutorial TOC, but need to know where we can insert that so that docs team will pick it up.

build_docs.py is run when importing the "API rule", which is usually always run at the same times as the "narrative rule"

Exactly, it's two separate tasks: "build the api-reference", and "import the docs directory", so there isn't really any hook you can use here. Automating it would have to be done on our side.

Obviously it's not too complicated if we have a good way to get a title and choose an order
(alphabetical?).

Subsites often forget to update their TOC. So we either need more testing or an auto-toc.

[gabrieldemarmiesse]

While we wait for an implementation in the tensorflow tooling, I think the best way forward for us to to have a light check in tools/testing/check_source_code.py