Week 2 :

• Renaming Directories

  • Completed with the very tedious task of manually renaming directories to properly index in Read the Docs platform.
  • The final commit to this task led to the directory structure of docs as :

  docs
  |
  |-- 0_Getting_Started
  |   |-- 1_Welcome
  |   |   |-- Overview.md
  |   |-- 2_Developing_an_AGL_Image
  |       |-- 0_Overview.md
  |       |-- 1_Preparing_Your_Build_Host.md
  |       |-- 2_Downloading_AGL_Software.md
  |       |-- 3_Initializing_Your_Build_Environment.md
  |       |-- ...
  |-- ...
  |-- ChapterNumber_ChapterName
      |-- SubchapterNumber_SubchapterName
          |-- ArticleNumber_ArticleName.md
  

  • The name directories of Chapter and Subchapter are directly rendered into the webpage (omitting “_"), but for the markdown articles, the title defined in the metadata overrides the file name but still including Article Number in the markdown file name is mandatory for indexing purposes.
  • This naming scheme was selected because reshuffling content and adding new chapters would lead to only renaming the top level directories.

• Overriding Default Read the Docs Theme

  • The default Read the Docs theme for Mkdocs doesn’t support collapsible side pane which becomes frustratingly long and bulky for a large number of markdown files as noticed here (on the left side pane).
  • Hence, the next step was to implement a slightly edited version of readthedocs theme called “Read the Docs Dropdown” supporting collapsible navigation. The problem with doing this is readthedocs build platform overrides the external themes to the default Read the Docs, this was done to properly inject the multiple version menu (on the bottom left).
  • The solution to this problem was found on stackoverflow and was sucessfully implemented.
  • Since using external theme was now a possibility, much any more different themes were tested, out of which some were successful with injecting the readthedocs version menu and most failed.
  • Various external themes tested out were :
    • Alabaster :
      • Doesn’t support the default readthedocs version menu.
      • Very simple and clean webpage and user interface.
      • No side panel for navigation.
    • Material :
      • Doesn’t support the default readthedocs version menu.
      • A very clean and interactive user interface looks great.
    • Bootstrap4 :
      • Doesn’t support the default readthedocs version menu.
      • Navigation on the top (especially for mobile view) is not suited for large table of contents.
    • Ivory :
      • Does support the default readthedocs version menu.
      • Pretty similar theme to readthedocs with a collapsible menu.
    • Windmill :
      • Does support the default readthedocs version menu.
      • Looks simple and great, definitely recommend this theme.