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,
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.
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 Marked with are completed while indicates an in-progress task.
Assess existing material
The Library Author’s
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
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.
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
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
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
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?