Documentation workflow for library authors

Scala Center Updates
1

Documentation Workflow for Library Authors

(The Scala Center team is dedicated to providing regular and transparent community updates about project plans & progress. In this forum we created a new topic category to allow quicker orientation going forward: “Scala Center Updates”. Even though all feedback is welcome, we keep the right to make executive decisions about projects we lead. Overview of all our activities can always be found at Scala Center Public Records)

Dear Scala Contributors,

A crucial component of any library is its documentation. At the same time,
producing high quality documentation is a complex and time-consuming activity.
The goal of this project is to guide authors and to provide them with reusable
configuration so that they can focus on content, rather than on setup, configuration,
and publication.

Motivation

It is important to provide library authors with a single, up-to-date and tested
path to easily publish documentation for their libraries.
Similarly, Continuous Integration configuration can be useful to improve the stability
of the codebase and to confidently release new versions.

This will enable library authors to focus on their code and documentation content.

Solution

This project will provide with documentation for

  • Setting up Continuous Integration (CI)
  • Setting up the generation of API documentation
  • Setting up the generation of a library site
  • Automatically publishing the website from CI

At the same time, these features will be introduced in a public repository so
that all the configuration is accessible to Library Authors.

Existing documentation will be updated.

Milestones

Milestones Marked with :white_check_mark: are completed while :construction: indicates an in-progress task.

Assess existing material :white_check_mark:

The Library Author’s
Guide already
contains information about continuous integration (testing), continuous delivery (releasing),
continuous publication (publishing documentation).

The library-example implements all
the features described in the guide.

Both resources depend on Travis CI.

Drop Travis CI in favor GitHub Actions :white_check_mark:

Both the guide and the library were updated to use GitHub Actions instead of Travis CI
following the recent changes of policy of the service.

In particular

  • This PR upgraded the
    library from Scala 2.12 to 2.13 and it introduced the latest stable sbt version
    besides dropping the deprecated tut in favor of mdoc
  • This PR migrated the library
    to GitHub actions
  • This PR made sure that the
    dependencies and plugins used by the libraries will be updated regularly
  • This PR updated the Guide to
    reflect the changes in the library, adopting GitHub Actions.

Investigate site generation solutions :white_check_mark:

Different solutions exist to generate a static documentation site.
Looking at the projects in the community build,
the most recurring solutions are

recurring is also the usage of mdoc to check and run code
snippets included in markdown files.

sbt-microsites is built on top of Jekyll and, therefore, requires the installation of
a Ruby environment. Docusaurus is built on top of React and relies on
a NodeJS install to generate the static site.
sbt-site in combination with Paradox offer a zero-install experience as this solution uses
the Java Virtual Machine and sbt to handle the entire process.
While it would be nice to avoid the heavy dependencies required by sbt-microsites and
Docusaurus, they offer a lot of flexibility and features which range from internalization
(for Jekyll) to website versioning (for Docusaurus).

Investigate a new solution :construction:

The new scaladoc brings about
many new useful features and more will come in the future.
The tool can generate API documentation as it did previously, but now it can manage a blog
and static pages. New versions support site versioning too.
Moreover, this tool is included in the Scala compiler so it could offer a zero-setup
experience.
This tool could also be easily integrated with mdoc.

However, the tool is new and a bit rough around the edges so we are currently evaluating
if it is ready to be used by Library Authors.

Implement the best solution

The chosen solution should be setup in the library-example repo and result in a PR.
It must support Scala 3.

Document the setup process

The solution implemented should be documented in the Library Author guide

Join the conversation

Any comment, feedback, suggestion or advice is welcomed!
In particular, library authors, let us know what were the major pain points and difficulties
in setting up your documentation or continuous integration?

9 Likes
2

Great initiative!
I have couple of suggestions and would like to hear what you (or the wider community) think of them:

  • Incorporate linting with Scalafix (Scalafmt is already present), especially OrganizeImports in particular, but maybe other rules, like ExplicitResultTypes could be useful for library maintainers
  • Employ Mergify to automatically merge PRs that Scala Steward makes
  • Renovate can update all the remaining things that Scala Steward can’t (like GitHub Actions, for example)
  • Use Coursier’s GitHub Action cache-action to speed up the build
  • Release Drafter GitHub Action makes writing release notes effortless
  • sbt-unidoc is useful when a library consists of multiple modules, which typically is the case, but I’m not sure how relevant this is with the new Scaladoc3

You can see all these tools, along with their configuration, in practice for example in the ZIO repository.

4 Likes
3

Great initiative, some notes about things, which would be good to have:

  • support of multiplatform libraries. Now, if the library supports JS and JVM, scaladoc for the shared folder is generated in both projects. And it’s unclear, where to write a static blog (needs the third subproject for this ?)
  • need some conventions for ‘package-scope’ documentation (which javadoc is looking in package-info.java).
  • In perspective, it would be good to see something like doclet API. [ common application is to draw dependency graph or hierarchy diagram]
1 Like
4

Hello @rssh!
Thank you for your input.

What do you mean by:

need some conventions for ‘package-scope’ documentation

I am not familiar with the doclet api. What feature are you interested in?

5

Hi @sideeffffect
Thank you for this list of interesting tools. There are definitely some interesting points here, I will look into them

6

In javadoc we have ‘packaga-info.java’. file, where a big text about package [package description]. is shown,
Here is java.nio (Java SE 16 & JDK 16) - summary of java.nio package, and here: jdk/src/java.base/share/classes/java/nio/package-info.java at master · openjdk/jdk · GitHub. is an appropriative documentation file.
With scaladoc, I don’t know where to put 'package-level. documentation. Event if such feature exists - I can’t discover it in the documentation. I can try to put scaladoc comment before ‘package’ entry, but what file to choose? If all package comments will concatenated into one or not? In what order?

Let’s assume the next use-case:
I’m a developer, wants to write a general package description, which should be available before the list of classes and top-level functions and objects in this package. I expect to see a phrase how to do this in scaladoc in scaladoc description.

Sorry, now it’s taglet API. Taglet Overview
Feature – I want to generate a dependency diagram or hierarchy or collect all TODO-s into a separate document via some custom code. For hierarchy, I want to have something like 'tag: @include-in-diagram in class code and taglet will change @include-in-diagram("name") to. see diagram [URL] .
I want to write such a taglet as a class that generate such a diagram and places it in the fixed place, relative to the docs root. Scaladoc should retrieve the taglet via some discovery mechanism and run it during processing.

On the other side, such taglet-like API is ‘nice to have.’ but not necessary.

1 Like
7

I understand better, thank you for clarifying.
The points that you raise are about the design of the language documentation tool, scaladoc, as it is responsible for generating package documentation as well as processing annotations or tags from the source code.
My proposal is more focused on documenting the usage of currently available tools in libraries.

I think that your experience with documentation in the Java world could be very useful in the discussions around scaladoc features.
I invite you to join the conversation in the following places:

1 Like