W04: Implementation
The fourth week was spent primarily on two things: the doctesting PR and implementing the Bulma front end into Documenter.
Doctesting stage
The first part of the week went into cleaning up and finishing off #774, the PR which introduces the doctest = :only option, allowing doctests to be run without having to run the full documentation build.
When I started testing it with the main manual, I had to come up with an alternative to how to apply the same DocTestSetups to multiple docstrings, which can currently be done by just having an @meta block before the relevant @docs block in the manual .md file that includes the docstring.
In the new system, doctests in docstrings are no longer influenced by the @meta blocks in the .md files. This is because when Documenter runs the docstring doctests, they are not associated with any particular manual page yet. The solution is to allow users to attach a DocTestSetup to a module instead which then applies to all the docstrings in that module (more detailed explanation here).
Once that was implemented, it was possible to test out the #774 branch on the main manual (JuliaLang/julia#32376). What this revealed though, since now all docstrings get doctested, not just the ones actually included in the manual, is that there are quite a few docstrings that are not included in the manual and contain outdated doctests.
Bulma front end in Documenter
The latter part of the week was spent on implementing the Bulma front end HTML in HTMLWriter, which is the module responsible for generating Documenter's HTML.
The WIP implementation lives in the draft PR #1043. In addition to modifying HTMLWriter, I have been cleaning up the SCSS, by being more systematic with class names, file layout etc.
I've also uploaded versions of Documenter and Julia manuals generated with that PR:
Note that these demos include changes from the next Monday as well.
Next week
The next week will be spent on continuing to work on the same PRs:
- Finish off and merge #774.
- Fix the failing doctests and unincluded docstrings in JuliaLang/julia#32376.
- Try to tag a release, or at least branch off master so that I could start merging front end changes too.
- Merge #1043 to have a first version of the new front end implemented. Additional modification and changes can be done in follow up PRs.