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
This is definitely possible. I think the best way to do it is to include the docs you want using sphinx
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
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
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
Thank you Jade for that pull request, for anyone reading it’s #28638
The previous example in the above chat is no longer working for me (chpl 2.9.0 pre-release 069a1c4c70f). Mason isn't able to find the included submodules anymore.
mason utils : /tmp/chpldoc-XXX.deleteme-QQxq4Y/source/modules/src/Foo/Bar.rst:23: WARNING: toctree glob pattern 'Bar/*' didn't match any documents
mason utils : /tmp/chpldoc-XXX.deleteme-QQxq4Y/source/modules/src/Foo/Bar.rst:31: CRITICAL: Problems with "include" directive path:
mason utils : InputError: [Errno 2] No such file or directory: '/tmp/chpldoc-XXX.deleteme-QQxq4Y/source/modules/src/Foo/Bar/A.rst'. [docutils]
mason utils : /tmp/chpldoc-XXX.deleteme-QQxq4Y/source/modules/src/Foo/Bar.rst:34: CRITICAL: Problems with "include" directive path:
mason utils : InputError: [Errno 2] No such file or directory: '/tmp/chpldoc-XXX.deleteme-QQxq4Y/source/modules/src/Foo/Bar/B.rst'. [docutils]
mason utils : error: building html output from chpldoc sphinx project
I haven't determined for sure yet if this is related to #28638 but I can try recompiling just before that commit.
Recompiling my install and rerunning mason doc fixed the issue. Thank you Jade!
1 Like
