Writing documentation for a PDK

ravn

Hey,

I have been building a PDK which is getting lengthy so I decided to clean up the documentation. I want to go with Sphinx and autodoc and have a few questions.

I have most of my code in separate .py-files so those can in principle be documented easily using autodoc. However, code found in .lym-files cannot documented this way since autodoc cannot import them. How do people do that?

Next thing is, some of my code uses the pya-module. How do I make this one available to autodoc?

Thanks,
Robert

dick_freebird

I guess my first advice would be "Know your audience". Or
audiences.

Are you trying to document the PDK for users, maintainers,
those who might build upon it elsewhere? All of these, some
of these? And do you believe they all want the same info, or
different "slices of the pie"?

In the commercial PDKs I have used, I have -never- seen (as
an IC designer just looking to get it done) code documented.
Only what the user might pass to it, maybe what some
function call wants and does.

Now probably in that foundry's PDK development group that
sort of software-design documentation exists, all trade-secret
and kept from prying eyes who aren't involved in its maintenance.

If I were writing a linear document I'd probably just refer to code
"appendix style" - call out where it can be found and the version
at hand, and let the reader do the legwork if they care. Then
you'd (you think) be dealing with a "pro" who doesn't need you
to embed all those lines in the top level document (and those
unwilling / incapable, you don't need to coddle idle curiosity).

Anyhow, "different horses for different courses" - figure out who
you're really trying to support and how much of what, do they need
to know? I think the tools are less important than deciding on
content and delivery.

"Do not concentrate on the finger or you'll miss all the heavenly glory"

• Bruce Lee, "Enter the Dragon"

Matthias

@ravn I'm slightly confused - as Jim mentioned a PDK usually does not document code but rather user facing things like devices, design rules, guidelines or physical things like electrical parameters, sheet resistances or nominal dimensions.

I guess you want to document code for your own purposes. But by using Sphinx you're applying a tool made for a Python ecosystem. KLayout is not a Python ecosystem, it embeds Python for the purpose of automation. pya is a binary module linked internally and lym files are the integration wrappers KLayout uses to bind Python code to menu items and configure them for autorun.

In order to simplify things, you can avoid .lym files and if you have to use them, simply let them import a .py file as a module. This way they become thin wrappers not worth being documented.

I can't help with autodoc. I don't know how this thing works and where it gets the documentation from. KLayout's pya provides docstrings, so for example help(pya.Box) works in the console. But you will get doxygen-like docstrings and I do not know how to transfer that to autodoc.

Matthias

ravn

Thanks for the fast feedback. What I wanted was really to document the code which is getting more contributors. So, I think Sphinx is a good options.

I managed to resolve the issue in my second question by making a dummy pya-module that is placed in the doc folder and only included by autodoc when generating the documentation. The dummy module can be found by autodoc only by adding

sys.path.insert(0, os.path.abspath('.'))

in the conf.py file for Sphinx.