Problem/Motivation

Past discussions have identified Doctum as being a good candidate for generating the low-level API (non *.api.php) docs for D12 and beyond. We should put some effort into building a new repo that holds a Doctum (or other SSG) config and theme so that we can spin up static, git versioned documentation for the docs.

In some local testing, I've found that these files will be quite large in size (+/- 900mb), so a new repo makes the most sense rather than simply hosting them directly out of core. However, I've opened the issue here so that we can track and discuss this effort in the context of other initiatives happening in the same space

Here is the official laravel API documentation, which uses Doctum to build: https://api.laravel.com/docs/master/index.html

Notice the version tags! It would be a good goal to try and replicate this.

Steps to reproduce

Proposed resolution

Remaining tasks

  1. Set up new api docs repo that holds generated docs
  2. Set up branch tagging that follows drupal core
  3. Set up CI jobs that cut a new release when Drupal core is released
  4. Provision a new domain that the new docs will live on
  5. Figure out how to include version / branch tagging into the URL so we can jump between different sites

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet

Comments

abenbow created an issue. See original summary.

abenbow’s picture

abenbow
He/Him/His
Primary language English
commented

Doctum doesn't appear to handle the following tags, so we have some missing code examples in the test I'm helping build.

  • @code/@endcode
  • @see

And possibly others. It would be good to get this cleared up (check Laravel's implementation) to get some ideas.

nicxvan’s picture

nicxvan commented

Can you share some links to where the discussion happened?

This looks interesting!

abenbow’s picture

abenbow
He/Him/His
Primary language English
commented
Title: Move Drupal Core API Docs into Doctum » Move Drupal Core API Docs into Doctum or other SSG
Issue summary: View changes
Related issues:
abenbow’s picture

abenbow
He/Him/His
Primary language English
commented
Related issues: +#3582087: Consolidate high level Drupal core documentation in markdown files and publish them via gitlab pages, +#3582253: Markdown docs for cache API

@nicxvan Most of the conversation around this particular effort came about as a result of some discussions I've been having with @quietone. We've been scratching our heads to try and figure out how to move along some of the talks about docs.

To my mind, there are essentially three major efforts to try and knock out in the documentation world right now.

  1. Make it so d.o. community docs can be moved into a git revisioned plaintext format (or md, or some other such thing) so people can a) earn contribution credits on community docs and b) make it easier to contribute to core and other projects without (quite as much) code knowledge (you'd still need to learn git and md for example)
  2. Move so-called "high-level" documentation (*.api.php files) into a /docs folder on core so it is easier write long form overviews of some very deep topics like the cache API. Here they will probably be served using mkdocs, deployed to gitlab pages, but still readable via gitlab's markdown preview, at least according to the general consensus. One of the first efforts to do that is with the cache API: https://www.drupal.org/project/drupal/issues/3582253 (I'll probably pop in on this one too)
  3. Split off other API docs into their own generative process that can be deployed via gitlab pages (that's what this ticket is!)

I've added a few more related issues (there are a lot) to this ticket to try and pull this all together.

A lot of the conversations that I've read so far have typically touched on more than one of the above efforts at once, so I'm sure there are more issues that have some bearing on this other than those that I've linked.

For my part, I'm going to use this issue as a place to try and track work towards a sort of "catchall" API docs site for generated documentation that comes directly out of the code comments. The other two issues of capturing and markdownifying the community docs and high-level docs can, therefore, have their own space so we can keep these channels a little more separated. @catch was the one to identify Doctum as a good system that was already in use by some other projects and I think that was a really good call.

quietone and I have been doing some adhoc builds when we have the time and think this would be a decent fit, though there are a few issues to iron out along the way.