Chpldoc - include submodule documentation in main module, hide elsewhere?

Users
1

Hello,

I have a module Bar that includes submodules to avoid excessive nesting in the import/use statement, but still allowing the implementations to reside in separate files. The submodule really only exists to contain a class, and its name feels redundant.

src/
  Foo.chpl
  Foo/
    Bar/
      A.chpl
      B.chpl
    Bar.chpl

// Foo.chpl
module Foo {
  include module Bar;
  public import this.Bar;
}

// Bar.chpl
module Bar {
  include module A;
  include module B;

  public use this.A;
  public use this.B;
}

// A.chpl
module A{
  class SomeClass {}
  // ...
}

such the user can import Foo.Bar.SomeClass rather than import Foo.Bar.A.SomeClass. However, I would like to move the generated documentation of A into the docs of Bar, and hide the module A (or at least duplicate documentation there) from the user. Is this currently possible with chpldoc? Or am I making this harder than it needs to be?

Currently I’m adding a note at the top of the documentation of A.chpl about how to best import, but I can’t override the default usage statement at the top

Related discussion I saw at How to structure classes as files

2

This is definitely possible. I think the best way to do it is to include the docs you want using sphinx

Screenshot 2026-03-31 at 1.24.55 PM
Screenshot 2026-03-31 at 1.24.55 PM742×565 13.1 KB

The way I created this was with the following sphinx docs in Bar.chpl

/*

  .. include:: /modules/src/Foo/Bar/A.rst
    :start-after: START_HERE

  .. include:: /modules/src/Foo/Bar/B.rst
    :start-after: START_HERE

*/

In A.chpl

/*
PRESTART
START_HERE
*/

However, this is not perfect, because Chapel will auto-include the submodule in the docs (this is true for any Chapel module). For that, you really need to do something custom like post-processing the rst and then calling sphinx-build yourself, which is not very satisfying. I could imagine a chpldoc attribute for modules like @chpldoc.noAutoInclude to prevent it from being automatically included. If something like that is interesting, consider opening an issue for it

Hope this helps!
-Jade

2 Likes
3

A slightly improved version is to have A look like this

/*
..
  START_HERE
*/
module A {
  class SomeClass {}
}

This makes the duplicated docs for A standalone look a little better (since START_HERE is hidden in a comment)

-Jade

1 Like
4

Hi Jade, I’ll go ahead and put in a feature request, but this is already a big improvement thank you. I’m not familiar with Sphinx so I’ll investigate the syntax a bit more, but in the mean time this will work.

1 Like
5

Thank you Jade for that pull request, for anyone reading it’s #28638