My primary task for this summer Outreachy internship is helping to optimize and update the documentation for the LibreHealth toolkit and create a static website using Sphinx documentation generator.
I had very little experience writing documentation and never used something like Wiki pages or Sphinx. All my READMEs were regular README.md files laid out with Markdown. When I started reading about Sphinx, I discovered two things:
- There is no «official» Markdown specification, Markdown rules and rendering can differ depending on a platform.
- Sphinx uses reST (restructured text), which is a lot like Markdown but has a clear specification and additional features.
I always want to try out things myself so I found a tutorial on the Sphinx website. It outlines how to create simple documentation with Content tree and links to sub-documents and instructions on how to build and run it locally. The tutorial is well-structured and you don’t need to have specific knowledge to go through it.
Another thing that I needed to do, was installing an IDE that supports Java. I have no experience with this programming language but based on previous revision on the project documentation and my experience working in JetBrains’ IDEs, I chose IntelliJ Community Edition. Community edition doesn’t have all features and integration options of the professional edition but it can be used for free and is enough as I was not going to write much (if any) code.
I’m relatively new to Linux and when it comes to installing programs that cannot be installed with apt-get install, I get stuck. I read a manual on installing IntelliJ on Ubuntu from an archive but on the last step I found out that I don’t have a file they were asking to move. There’s a lifehack for those who are like me: you can use Ubuntu Software Center and look for the needed program. It worked for me and in just two mouse clicks I got a running IDE with a familiar layout (all JetBrains’s IDEs that I’ve seen have a similar layout, settings, and tools).
It’s a little weird to see the code in a language you don’t know. When I just started to learn to code, everything looked bizarre and I didn’t understand a thing. Now when I try to read a Java code, I notice familiar patterns like loops or functions and classes but they have different syntax and it’s not always clear what happens in the code.
So learning a little about the tools I will be using and setting up work environment on my machine were the first steps of my summer internship. I’d use the same steps for any new project:
- Learn the main tools.
- Set up work environment.
You will both have a possibility to run a project locally (if it can be done) and become familiar with the tools others are using.
You can see the documentation website that I’m working on here: https://docs.librehealth.io/.