Status update, October 2019
Oct 19, 2019 · 3 min read
A lot has been happening the last month, we have started working on the largest group software development project at the University. We are a team of six people, and have decided to choose Go as our language of choice for the implementation of the smart home system we are building.
We have spend the first couple of weeks setting up the group in GitLab and
get continuous integration running (so we can have LaTeX PDF builds, and wiki
site deployed automatically). While setting up all the documentation for the
team and project, and specifying the software development process of the team,
we realised that there is no simple way and neat way to generate a Go project
documentation automatically – something like JavaDoc or Doxygen. Using the
go doc -all command to generate documentation isn’t great, as it simply
dumps the documentation in plain text, with no option to change the format.
Some solutions I have found on the Internet is to run the
(which is what hosts Go’s project homepage), then to use
wget to download
the HTML pages. The downside of this process is:
- Customising the template or layout of the pages is difficult, requiring you to fork the project and change many lines of code.
- The project has to be located in the
GOPATH, otherwise it will not be detected. Our project is usually hosted outside of the
GOPATH, as we are using Go modules.
I tried to find a documentation generator, and sadly Doxygen doesn’t support Go – which may be a good thing (some project members simply didn’t like the style of it). And we cannot use the GoDoc website as the projects are hosted on a private GitLab group.1
After some more searching, I found a project called godoc2md by Dave Cheney, which promised to do exactly what I have wanted to do. After trying to get it compiled and running, I have encountered many compilation errors, mostly due to changes to the GoDoc package which the project depends on. So this seems like a dead end.
I have noticed the output of
go doc -all is easily parsable, different lines
are formatted differently, which allows me to easily identify which section of
the documentation is a function declaration, description, etc. With this I can
write a simple program, using some regular expressions to detect different
parts and format them correspondingly. And godoc2markdown is born, although
it has some quirks which I am ironing out as the project progresses.
I’ll leave you with a picture of a project I have been working on, more details to be released soon.
That’s all for this month!
As we aren’t allowed to post the project source publicly until the end of the course. ↩︎
Articles from blogs I follow around the net
These articles do not represent my opinions or views.
Making My Website More Accessible [//]: # "" Written By: Jake Bauer | Posted: 2020-02-06 | Last Updated: 2020-02-06 For about one and a half months now I've been working on redesigning paritybit.ca to make it more accessible. In that time I've…via paritybit.ca - Blog February 6, 2020
I’m 34,018 feet over the Atlantic at the moment, on my way home from FOSDEM. It was as always a lovely event, with far too many events of interest for any single person to consume. One of the few talks I was able to attend1 left a persistent worm of thought …via Drew DeVault's Blog February 6, 2020
KnightOS is an operating system I started writing about 10 years ago, for Texas Instruments line of z80 calculators — the TI-73, TI-83+, TI-84+, and similar calculators are supported. It still gets the rare improvements, but these days myself and most of the…via Drew DeVault's Blog January 27, 2020
Automating the Publishing of Articles Written By: Jake Bauer | Posted: 2019-12-30 | Last Updated: 2019-12-30 If you're seeing this, it means my automation script worked perfectly. There was too much manual work involved in publishing things to my website…via paritybit.ca - Blog December 30, 2019
Generated by openring