Issue with rendering the course

[sarthak247]

If we try to render the course to preview how our added content looks like, it throws the following error

sarthak@kde:~/Desktop/computer-vision-course$ doc-builder preview computer-vision-course chapters/ --not_python_module
Initial build docs for computer-vision-course chapters/ /tmp/tmp0uqdjoxf/computer-vision-course/main/en
Building the MDX files: 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 29/29 [00:00<00:00, 1288.27it/s]
Traceback (most recent call last):
  File "/home/sarthak/anaconda3/bin/doc-builder", line 8, in <module>
    sys.exit(main())
  File "/home/sarthak/anaconda3/lib/python3.9/site-packages/doc_builder/commands/doc_builder_cli.py", line 47, in main
    args.func(args)
  File "/home/sarthak/anaconda3/lib/python3.9/site-packages/doc_builder/commands/preview.py", line 171, in preview_command
    source_files_mapping = build_doc(
  File "/home/sarthak/anaconda3/lib/python3.9/site-packages/doc_builder/build_doc.py", line 405, in build_doc
    sphinx_refs = check_toc_integrity(doc_folder, output_dir)
  File "/home/sarthak/anaconda3/lib/python3.9/site-packages/doc_builder/build_doc.py", line 460, in check_toc_integrity
    raise RuntimeError(
RuntimeError: The following files are not present in the table of contents:
- en/Unit 5 - Generative Models/variational_autoencoders
- en/Unit 5 - Generative Models/README
- en/Unit 11  - Zero Shot Computer Vision/README
- en/Unit 2 - Convolutional Neural Networks/README
- en/Unit 1 - Fundamentals/README
- en/Unit 8 - 3D Vision, Scene Rendering and Reconstruction/README
- en/Unit 4 - Mulitmodal Models/README
- en/Unit 9 - Model Optimization/README
- en/Unit 6 - Basic CV Tasks/README
- en/Unit 7 - Video and Video Processing/README
- en/Unit 13 - Outlook/README
- en/Unit 3 - Vision Transformers/README
- en/Unit 12 - Ethics and Biases/README
- en/Unit 10 - Synthetic Data Creation/README
Add them to chapters/_toctree.yml.

Explanation: This is because there have been README files added to each chapter. However, these README files are not present in the _toctree.yml.

Why it's important: Being able to render the course locally is important as it can give us a rough overview of how the content looks like.

Possible solutions could be:

• Remove the README files for the time being
• Add them to the toctree and also making sure that if anyone adds any chapter contents they also update the toctree making it easier for others to render the course

Open for discussion from other members :v:

[klyap]

Oh I didn't realize we were supposed to use doc-builder to preview the course. I've just been using this VSCode plugin https://marketplace.visualstudio.com/items?itemName=xyc.vscode-mdx-preview

EDIT: OH this button doesn't work for rendering LaTex with $...$ syntax as recommended in the README? Maybe because that's coming from Github MathJax rendering? https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions

[sarthak247]

Thank you for that. I'll have a look at that VSCode extension. I just thought of going with doc-builder for now as I was following the style guide and structure from HF Audio Course and they were using doc-builder to render the course locally so I thought something similar could be used here as well.

[johko]

Pinging @merveenoyan and @MKhalusova , as they probably know most about doc-builder

[MKhalusova]

To publish on hf.co/learn, we indeed use the doc-builder. You can learn more about it in its repo: https://github.com/huggingface/doc-builder

It does require that all the .md files in the folder it builds are also in the _toctree.yml. Both solutions suggested will work. I would also recommend having an introduction.md in each chapter as a "landing" page for each chapter.

As a third option, while the work is still in progress, the content of readme files can move into introduction files. Later you can turn them into actual introduction pages with "what to expect" paragraphs, for instance.