documentation generation enhancements

[mfelsche]

the docgen process is currently set up so it creates documentation for the code inside the given directory and all reference packages. It documents private types as well as public ones and also includes test types.

I would like to be able to generate and publish API documentation for a pony project. With the current setup i need to manually go through the generated files and exclude stuff from builtin, collections and other packages. I also need to remove test classes and types and private methods and types.

I would like the docgen process to be able to:

• only create docs for public types in the package in the given directory
• optionally recursively including packages in sub-directories

Given these changes it is possible to create useful project API documentation only by using ponyc --docs . (possibly some more arguments) and calling mkdocs afterwards.

Given this is a wanted feature, i could start working on it.

---

This idea started from an IRC conversation with SeanTAllen:

18:45 <vaninwagen> SeanTAllen concerning the docgen question i had, do you think it is worth putting any effort into adapting 18:45 <vaninwagen> SeanTAllen concerning the docgen question i had, do you think it is worth putting any effort into adapting the docgen part to be able to create public API for the local package only? 
18:45 <vaninwagen> From my side this is pretty useful as i could use it to create and publish some API docs for ponycheck 
18:45 <vaninwagen> should an idea like this go through the RFC process? 
18:50 <vaninwagen> if it makes sense in the first place 
18:55 <SeanTAllen> vaninwagen: i think its reasonable. i don't think an RFC is needed as long as it is adding functionality. that said, i think discussion would be good. this could be either on the developer mailing list, an issue on ponyc repo, or in person during the sync call. 
18:55 <SeanTAllen> is there a particular format you prefer? i think any of the 3 works fine. 
18:57 <vaninwagen> SeanTAllen i'd say it should definitely be somehow in written form. I'd prefer a github issue (optionally with additional sync call) tbh. 
19:02 <SeanTAllen> Open a github issue as an enhancement. reference this conversation here. and bring up what you want to accomplish and why and we can start to collect feedback. the document generation as far as i know has only seen usage with the standard library. 
19:03 <SeanTAllen> So it could certainly use more loving. I'm glad you have interest in the area. I'm not particularly fond with it being tied to mkdocs but I wasnt going to touch that until we had "pony in pony" for the compiler so it would be easier to get contributions 

[SeanTAllen]

"only create docs for public types in the package in the given directory" has been added #2092

[SeanTAllen]

Take away from sync.

The current document generation has only (afawk) been used for standard library docs. There are changes that we want to make to allow docgen to be useful to libraries.

What we want to be able to do is only include documentation for classes defined in a library or application and not bring in documentation from other libraries. To do this, we would supply a top level path for the library/app (perhaps inferred). We should be able to compare against the package path available in docgen to verify that the package path in question is below our top level path. If it is, we can include otherwise filter out.

[SeanTAllen]

IF you are interested in this project that falls under the "ponydoc" category, talk to me. I have started a lot of work on this.