Experimental documentation system

Beman Website and Docs
1

At C++Now two weeks ago, I was talking with some folks about how we might do the documentation system for Beman. I have implemented a toolkit that is an initial attempt at this.

The repo for it is on Github. It has online docs that are implemented using the toolkit itself. There is a link at the bottom of the README.md to the online docs. Direct link: https://tzlaine.github.io/beman_doc_tools.

The technologies used are Docusaurus, Doxygen, and Moxygen (which converts Doxygen XML to Markdown). The intent is that all documentation is written in Markdown, even the generated Doxygen API docs.

Please have a look at the tutorial, and let me know if anything is confusing, and/or how you think things can be improved. Also, please try it on your favorite Beman library repo, and let me know how it works. I’ve been developing it using GitHub - tzlaine/transform_view: An update version of std::ranges::transform_view that enables conditional borrowability. as my example Beman lib, and so far so good. :slight_smile:

This repo is a separate thing at the moment, but it may be a candidate for including in the Beman infrastructure repo, exemplar, or …? Please also weigh in on where this toolkit should live.

1 Like
2

Great job Zach!

Do you have a link or a screenshot to the generated documentations?

3

No, but if you follow the beman_doc_tools doc link above, you’ll see what kind of docs it generates.

4

Looks like a great start!

Looking at the source here this one is just using Docusaurus – is that right? Do you have a link of rendered docs for transform view that includes doxygen outputs?

Yeah, idk where the best place is at the moment so I think it’s fine on its own for now. In my view it would be nice to xfer it under Beman project for visibility and commit permissions management.

It does seem like you’re going to have a lot of resource overlap with the website from what I’m seeing there – but still it’s not clear that we’d want these to be in the same repo. Probably a discussion topic for the sync meeting at some point.

5

Finally got around to publishing the rendered docs for transform_view:

1 Like
6

At least for mobile, it looks like links might be broken. They are printing out literally instead of linking to other markdown files.

7

I’m probably holding it wrong, and I’ll try again on a different laptop, but:

sdowney@PW054KK7:~/src/sdowney/Optional26/docusaurus/beman_doc_tools (main ±)
$ node run build_starter_docusaurus_tree
node:internal/modules/cjs/loader:1228
  throw err;
  ^

Error: Cannot find module '/home/sdowney/src/sdowney/Optional26/docusaurus/beman_doc_tools/run'
    at Function._resolveFilename (node:internal/modules/cjs/loader:1225:15)
    at Function._load (node:internal/modules/cjs/loader:1055:27)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:220:24)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:170:5)
    at node:internal/main/run_main_module:36:49 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}

Node.js v22.14.0

docusaurus is a checkout of optional, and beman_doc_tools is a clone of the repo within the checkedout optional.

8

At least for mobile, it looks like links might be broken. They are printing out literally instead of linking to other markdown files.

This was easily addressed. It was user error – I was using backtick-quoting to get code font for some words in my Doxygen quotes, but if you do that for Doxygen-indexed entities, the quoting wraps the link, leading to the misbehavior you saw.

I added a note in the online docs explaining this.

9

The fact that it cannot find even the node run “module” seems like maybe you forgot to do npm install first. Otherwise, I don’t think I know what’s going on there.

10

I implemented the code quoting stuff I mentioned at the sync up yesterday. Docs forthcoming soon.

11

Docs for the code sampling feature are now up.