[agl-dev-community] GSoD Weekly Update: Week 2

["Shankho Ghosh" <shankhoghosh123@xxxxxxxxx>]

Week 2 :
--------------

-   Renaming Directories :
    -   Completed with the very tedious task of manually renaming
directories [1] to properly index in Read the Docs platform.
    -   The final commit [1] 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 filename but
still including Article Number in the markdown file name is mandatory
for indexing purposes.
    -   This naming scheme was selected because of 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 a
collapsible side pane which becomes frustratingly long and bulky for a
large number of markdown files as noticed here [2] (on the left side
pane).
    -   Hence, the next step was to implement a slightly edited
version of readthedocs theme called "Read the Docs Dropdown" [3]
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 [4]
and was successfully implemented [5].
    -   Since the external theme was now a possibility, much 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 [6] :
            -   Doesn't support the default readthedocs version menu.
            -   Very simple and clean webpage and user interface.
            -   No side panel for navigation.
        -   Material [7] :
            -   Doesn't support the default readthedocs version menu.
            -   A very clean and interactive user interface looks great.
        -   Bootstrap 4 [8] :
            -   Doesn't support the default readthedocs version menu.
            -   Navigation on the top (especially for mobile view) is
not suited for a large table of contents.
        -   Ivory [9] :
            -   Does support the default readthedocs version menu.
            -   Pretty similar theme to readthedocs but with a collapsible menu.
        -   Windmill [10] :
            -   Does support the default readthedocs version menu.
            -   Looks simple and great, definitely recommend this theme.

[1] : https://github.com/growupboron/agl-docs/commit/7e2b9d0ddf541104b368c6c635f36b536aed68c5
[2] : https://agl-docs.readthedocs.io/en/master-rtd-default/
[3] : https://github.com/cjsheets/mkdocs-rtd-dropdown
[4] : https://stackoverflow.com/questions/37952916/can-i-use-external-themes-with-mkdocs-on-readthedocs-org
[5] : https://github.com/growupboron/agl-docs/commit/ce1c483c061c81d572fa9dc53e12ec998ef2371a
[6] : https://agl-docs.readthedocs.io/en/master-albaster-0309/
[7] : https://agl-docs.readthedocs.io/en/master-material-0309/
[8] : https://agl-docs.readthedocs.io/en/master-bootstrap4/
[9] : https://agl-docs.readthedocs.io/en/master-ivory/
[10] : https://agl-docs.readthedocs.io/en/master-windmill/

Regards,
Shankho Boron Ghosh
Junior, Electronics & Communication Engineering
Thapar Institute of Engineering and Technology
+91 9819674639
growupboron.github.io/

-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.

View/Reply Online (#8632): https://lists.automotivelinux.org/g/agl-dev-community/message/8632
Mute This Topic: https://lists.automotivelinux.org/mt/76657361/2167316
Group Owner: agl-dev-community+owner@xxxxxxxxxxxxxxxxxxxxxxxxx
Unsubscribe: https://lists.automotivelinux.org/g/agl-dev-community/leave/4543822/883735764/xyzzy  [list-automotive-discussions82@xxxxxxxxxxx]
-=-=-=-=-=-=-=-=-=-=-=-