Documentation tools for Julia

This is the submission for the Google Summer of Code 2016 project Documentation tools for Julia, by @mortenpi, mentored by @MichaelHatherly.

A big part of Julia is its package ecosystem and their documentation should be as thorough as possible and documenting packages should be made as easy as possible for package developers.

The primary goal of the project is to extend Documenter.jl so that it could also generate a detailed reference manual of functions, types, submodules etc. with full signatures and a search capability. The idea is to complement the docstring, since sometimes you need this detailed information and it should be easily accessible (reading the code or using introspection methods is cumbersome).

A secondary goal is to lay the groundwork for a comments/notes system, where the community could more easily contribute to the docs (of both Base and packages).

During the project I participated in the development of Documenter.jl – a Julia package for generating documentation of other Julia packages. In a nutshell it works by combining user-written manual pages with in-code docstrings and other information to produce useful and up-to-date docs for a Julia package.

Over the summer I worked on several aspects of the package, successfully submitting multiple PRs to Documenter.jl, with most of the time and effort going into three new features described below. In addition to that I also made a few minor contributions to other packages and to the Julia repository itself (in the form of small PRs, reported issues etc).

To familiarize myself with the code base I started off by adding a function, generate(pkgname), to Documenter, which allows a package developer to easily generate a documentation stub, making it easier to set up Documenter for a package. This was merged into Documenter in #66.

After that I started working on auto-generated lists of methods to complement the docstrings in the documentation. In Julia every function can have multiple methods attached to it that differ by the function signature, and it would be useful if the users have access to this information in the documentation. This was merged into Documenter in #90. Later in the summer this was removed from Documenter though, in favor of the more versatile DocStringExtensions package.

The final and largest part of the project was implementing native HTML output for Documenter. Documenter basically works by taking a set of Markdown files that the user has written, copy-pastes in docstrings from the code and outputs the result. Up to that point the output had been another set of Markdown files that would then be processed further by other tools, suck as MkDocs. However, having Markdown files as output can be rather limiting, hence the need for a native HTML output.

My work here involved implementing the new renderer that would convert the internal data structures into HTML files, and creating the front-end matters, such as the style and integrating some Javascript widgets like search and code highlighting. The main part of the solution was merged into Documenter in #171, with some additional preparatory work in other PRs.

After being merged, the HTML rendering was also released as an optional experimental output format as part of v0.3 of Documenter.jl. The release and the availability of the HTML output was also announced on the julia-users mailing list. I have since been working on bugfixes and enhancements and I have compiled a list of TODOs and possible improvements into #212, and we are actively gathering feedback from users who are trying of this feature.

Statistics wise, the GitHub contributors page for Documenter shows that I contributed nearly +3000/-800 SLOC of new, changed and removed code over 39 commits.