Rework the documentation hosting & generation and Restructure getting started pages and developer guides

This report is a requirement of the Project finalization phase of Google Season Of Docs program. I worked with the Linux Foundation, under Automotive Grade Linux on the project to Rework the documentation hosting & generation and Restructure getting started pages and developer guides, the original proposal for the project can be found here.

logo-gsod,lf,agl

The Linux Foundation is the nonprofit consortium dedicated to fostering the growth of Linux. Automotive Grade Linux is an open-source project hosted by The Linux Foundation that is building an open operating system and framework for automotive applications.

Project Deliverables

The primary aim of the project is to simplify the existing AGL documentation workflow pipeline by reworking the documentation hosting and generation :

  1. Develop a single repository setup from the current multiple repository setup to improve the maintainability of the documentation site.

  2. Simplify the indexing of the existing markdowns by using directory tree structure instead of maintaining yml indexes.

  3. Migrate the whole setup from the current Jekyll template to MkDocs static site generator which can be hosted at readthedocs which simplifies :

    This setup would vastly improve and simplify fetching the markdowns of different releases of AGL from multiple repositories hosted mostly on gerrit into different branches on a single documentation repository setup.

  4. Improve the Getting Started page and Developer guides the existing documentation along with writing new documentation into the following clear and bullet-proof structure :

    • Tutorials: a lesson that allows the newcomer to get started.
    • How-to Guides: a series of steps that show how to solve a specific problem.
    • Reference: a technical description describing the appropriate machinery and workflow processes.
    • Explanation: discursive explanation explaining code/workflow structure in detail.
  • Rewrite the documentation of existing “How to handle documentation” to the proposed setup and with the aim of making it beginner and developer-friendly.

Ultimately, making the documentation community driven so users can report any issues of the documentation and also be able to make changes that will be reviewed and merged by the AGL team.

Community Bonding

Owing to timezone differences, my mentor and I scheduled the right time and medium for contact: triweekly Zoom Calls and constant communication over Telegram and IRC. Further refinement of objectives and goals were set to ensure that the proposed framework of the documentation site was in line with the priorities of the organization. Setup the personal blog to log progress for future reference and help future Google Season of Docs applicants and aspiring technical writers alike. I started engaging actively within the AGL community by regularly participating in the Weekly Developer Call. Since I had prior academic commitments and was already well accustomed to the AGL community. We decided to go ahead with the Documentation Development Phase earlier than the GSoD timeline.

Documentation Development

Migrating to MkDocs and ReadtheDocs

To simplify the documentation site generation and maintenance from the earlier four repositories setup, it was decided to host the documentation site on ReadtheDocs using the robust and mature static site generator called MkDocs.

MkDocs uses markdown as its markup language, and many of its strengths come from the power and straightforwardness of markdown and its flexibility to maintain documentation. To ensure that every AGL user and developer would be able to easily navigate through the documentation, multiple mockup were created using different themes like ReadtheDocs, Alabaster, Material, Bootstrap4, Ivory and Windmill. Windmill was finalized after discussion with the mentor and the AGL community mainly due to a clean and simple user interface with high responsiveness in mobile view and default collapsible navigation pane suiting AGL’s documentation index.

It was then decided to maintain the master version and new releases (>=jellyfish) of AGL on the new workflow and archive the older versions (=<icefish) by transferring it to old-docs.automotivelinux.org.

Currently, we are in the process of adding a CI configuration to build the MkDocs documentation directly from Gerrit. This way, every change request merged to the repository is reflected on the readthedocs site in a couple of seconds.

Revising and Rewriting AGL documentation

  • Major restructuring for segregation of Tutorials, How-to Guides, Reference, and Explanation.
  • Removing obsolete images and information with updation of relevant sections.
  • Reexamining build commands and verifying developer instructions on the corresponding platforms like Raspberry Pi 4 and QEMU.
  • Added Contribution Guide that will help newcomers and active community members alike.
  • The final docs/ structure : 
    docs                    # https://git.automotivelinux.org/AGL/documentation/tree/docs
├── 0_Getting_Started
│   ├── 1_Quickstart
│   │   └── Using_Ready_Made_Images.md
│   └── 2_Building_AGL_Image
│       ├── 0_Build_Process.md
│       ├── 1_Preparing_Your_Build_Host.md
│       ├── 2_Downloading_AGL_Software.md
│       ├── 3_Initializing_Your_Build_Environment.md
│       ├── 4_Customizing_Your_Build.md
│       ├── 5_0_Building_the_AGL_Image.md
│       ├── 5_1_x86_Emulation_and_Hardware.md
│       ├── 5_2_Raspberry_Pi_4.md
│       └── 5_3_RCar_Gen_3.md
├── 1_Hardware_Support
│   └── Overview.md
├── 2_Architecture_Guides
│   ├── 1_Introduction
│   │   ├── 0_Overview.md
│   │   └── 1_AGL_Requirements_Specifications.md
│   └── 2_Security_Blueprint
│       ├── 0_Overview.md
│       ├── 1_Hardware.md
│       ├── 2_Secure_Boot.md
│       ├── 3_Hypervisor.md
│       ├── 4_Kernel.md
│       ├── 5_Platform.md
│       ├── 6_Application.md
│       ├── 7_Connectivity.md
│       ├── 8_Update_OTA.md
│       ├── 9_Secure_development.md
│       └── Annexes.md
├── 3_Developer_Guides
│   ├── 1_Application_Framework
│   │   ├── 0_Introduction.md
│   │   ├── 1_afm-daemons.md
│   │   ├── 2_widgets.md
│   │   ├── 3_widgets_overview.md
│   │   ├── 4_Widget_configuration_file.md
│   │   ├── 5_Permissions.md
│   │   └── 6_Quick-Tutorial.md
│   ├── 1_Setting_Up_AGL_SDK.md
│   ├── 2_Application_Framework_Binder
│   │   ├── 0_Overview.md
│   │   ├── 1_Binder_daemon_vocabulary.md
│   │   ├── 2_How_to_write_a_binding.md
│   │   ├── 3_Binder_References.md
│   │   ├── 4_Binder_events_guide.md
│   │   ├── 5_Binder_Application_writing_guide.md
│   │   ├── 7_Document_revisions.md
│   │   ├── Annexes
│   │   │   ├── 1_Migration_to_bindings_v3.md
│   │   │   ├── 2_WebSocket_protocol_x-afb-ws-json1.md
│   │   │   ├── 3_Installing_the_binder_on_a_desktop.md
│   │   │   ├── 4_Options_of_afb-daemon.md
│   │   │   ├── 5_Debugging_binder_and_bindings.md
│   │   │   ├── 6_LEGACY_Migration_from_v1_to_v2.md
│   │   │   └── 7_LEGACY_Binding_v2_references.md
│   ├── 2_Creating_a_New_Service.md
│   ├── 3_AppFW_Privileges_Management
│   │   └── AppFW-Privileges_Management.md
│   ├── 3_Creating_a_New_Application.md
│   ├── 4_AFB_Helper_Guide
│   │   ├── 1_Usage.md
│   │   ├── 2_AFB_Timer.md
│   │   ├── 3_CURL_wrapper.md
│   │   ├── 4_URL_Escaping.md
│   │   ├── 5_Filescan_Utils.md
│   │   ├── 6_Qt_AFB_Websocket_client.md
│   │   ├── 7_JSON_library_for_modern_C++.md
│   │   └── 8_C_JSON_Wrapper.md
│   ├── 5_Using_CMAKE_Applications_Module
│   │   ├── 1_Project_Architecture.md
│   │   ├── 2_Configuring_AGL_CMake_Templates.md
│   │   ├── 3_Advanced_Usage.md
│   │   ├── 4_Advanced_Customization.md
│   │   ├── 5_Autobuild.md
│   │   └── 6_Using_CMake_Templates_from_Bitbake_Recipes.md
│   └── 6_AGL_Layers
│       ├── 1_Overview.md
│       ├── 2_meta-agl.md
│       ├── 3_meta-agl-demo.md
│       └── 4_meta-agl-devel.md
├── 4_APIs_and_Services
│   └── 0_API_Reference.md
├── 5_How_To_Contribute
│   ├── 1_Getting_Linux_Foundation_account.md
│   ├── 2_Using_Jira_for_current_work_items.md
│   ├── 3_Working_with_Gerrit.md
│   ├── 4_Submitting_Changes.md
│   ├── 5_Reviewing_Changes.md
│   ├── 6_Gerrit_Recommended_Practices.md
│   ├── 7_General_Guidelines.md
│   ├── 8_Adding_Documentation.md
│   └── 9_Contribution_Checklist.md
└── index.md

Work Done

Final documentation site rendered at docs.automotivelinux.org.

NOTE: Some of the Change Requests might be going in through review and further changes can take place. Final GSoD work product as of the submission of this report : agl-docs.readthedocs.io.

Commits

Weekly Updates

All of the progress is well documented in the form of weekly updates over the agl-dev-community mailing list and personal blog :

Final Comments

Future Work

Challenges

  • Becoming proficient with AGL developer tools, especially Gerrit has been quite a worthwhile effort.

  • Balancing academics along with GSoD was quite hectic but due to the mutual understanding with the mentors, I was able to overcome this.

What did I learn?

  • I learned a lot more about Automotive Grade Linux organization especially their developer tools, workflow, and developmental pipeline.

  • I was also able to learn how to use the MkDocs static site generator and readthedocs documentation platform.

  • My technical writing skills have definitely become better and have led me to contribute more effectively and robustly to academic research projects.

Post GSoD

  • I plan to maintain and add to the Automotive Grade Linux’s documentation repositories for the foreseeable future and work on continually improving it.

  • I will keep contributing and help other new contributors to explore and learn projects in this organization.

  • This project gave me the necessary experience and rigor to contribute meaningfully and efficiently to my role as Data Acquisition Engineer for FSAE Team Fateh.

  • I plan to continue my involvement here at Automotive Grade Linux for the foreseeable future and also take part in Google Summer of Code and continue my involvement with open source because it is the future and the best technique of learning is by doing.

Acknowledgements

I would like to express my gratitude to my mentors Jan-Simon Möller and Walt Miner for mentoring me through GSoD and also to the whole AGL community for being so inclusive and friendly.

Overall, It was one of the best professional experience that I undertook this year. I have been fascinated with AGL for as long as I have been a Data Acquisition Engineer for FSAE Team Fateh and the fact that I was able to contribute to the organization is an honor.