Fifth Week [June 17th - June 23rd] [2nd PSF Blog Post]

Published: 06/24/2019

Last week, I had completely cleaned the script I had for deploying the documentation, with help from Jaladh Singhal. As I had a misconception of what exactly is published to the gh-pages and how. I learned that the root contents in the gh-pages branch are what is published directly. 

This week, I finished publishing the documentation on gh-pages. The version on my forked repository can be seen here: As stated last week, I learned the required language to edit Sphinx files to publish the documentation. The selected language was restructured text reST. I editied *.rst files so sphinx can convert them into *.html files. 

After that, I installed and tested a self hosted agent on my computer, then later did the same on a remote server, which will later be used to test more intensive builds. Instead of using the supplied azure hosted agents to test and build TARDIS on a virtual machine, we willl also use a self hosted agent for more computational duties. The documentation has already been added to the link above. This also contains a pre-existing environment, which could save time in the future for other purposes. I also added a simple pipeline file that does not trigger to test the self hosted vm.

I had one unwelcomed incident from github, as I was attempting to add author properties to my commit, and ended somehow diverging a bunch of my commits for more than one branch into different new named commits. I solved this using by rebasing and reseting onto the main tardis branches. 

There was some difficulty learning reST, as how to reference links or how to make visual diagrams, but through looking at our organization's already made documentation, I was able to decipher that I also needed to include the file name I had made, containing value-pairs of names to links, in the main rst index file. In addition to realizing that github does not show the diagrams made in rst file, and that I would have to see the update in the html links.

The biggest challenge I faced was a minor problem with the self hosted agent. One must intuitively add an agent to an agent pool. I could simply create an agent pool, and add agents to it after adopting the proper permissions, but for some reason it did not work for the already existing pool called "default", which is owned by azure pipelines, but is meant to host self hosted agents. I later discovered that one requires even more permissions, and added in the documentation how to give someone all the permissions, that the creater of the project [tardis, my mentor] on azure, has.

Highlights of what I learned:

-Restructured text

-Publishing documentation on gh-pages

-Installing and running self hosted agents for pipeline builds

1000 characters left