The PSLab Android App and the PSLab Desktop App come with built-in experiments which include the experiment setups as well as the experiment docs. The experiment docs for PSLab have been written in the Markdown format. So, the markdown support had to be enabled in the PSLab Android App.
There are numerous markdown file renderers for android. The most popular among them is MarkdownView (https://github.com/falnatsheh/MarkdownView) which is an open-source service.
This blog covers how to enable the support for markdown in apps and use to generate elegant documentation.
MarkdownView can be enabled by simply adding a dependency in the build.gradle file
Creating the layout file
The layout file for supporting a markdown file is fairly simple. The inclusion of the above dependency simplifies the things. The view holder for markdown is created and an id is assigned to it.
Loading the markdown file
In order to load the markdown file, a MarkdownView object is created. Since, in the PSLab Android app, markdown files which form the documentation part are a part of the experiments. So, the files are displayed in the documentation fragment of the experiments.
The MarkdownView object created is assigned to markdown viewholder of the relevant layout file. Here, the layout file was named experiment_doc_md and the view holder was assigned the id perform_experiment_md. The markdown files were stored in the assets directory of the app and the files were loaded from the there.
The available methods in markdown view are
- loadMarkdown – loads directly from the content in the string
- loadMarkdownFromAsset – loads markdown files located in the assets directory of the app
- loadMarkdownFromFile – loads markdown from a file stored in the app not present in the assets directory
- loadMarkdownFromUrl – loads markdown from the specified URL (requires internet connection, as file is loaded from the web)
Important points for consideration
- Avoid using elements of GitHub Flavoured Markdown (GFM) as it is not fully supported. It is better to stick to the traditional markdown style.
- While adding images in the markdown files, avoid using specific dimensions as the images may not load properly in some cases due to the wide variety of screen sizes in android devices.
- It is better to store the Markdown files to be loaded in the assets directory of the app and load it from there instead of the other methods mentioned above.
- A comprehensive markdown tutorial to learn markdown scripting https://www.markdowntutorial.com/
- MarkdownView repository on Github by tiagohm https://github.com/tiagohm/MarkdownView
- Learn more about Github Flavoured Markdown (GFM) https://guides.github.com/features/mastering-markdown/