PyDoc within netlab / code comments

[snuffy22]

I was looking around the repo and wondering if most of the PyDoc like comments above functions are 'meant' to be PyDoc or just general commentary about what the functions are doing.

[ipspace]

Let's just say that someone started this project to learn Python 🤷‍♂️ and the early code definitely reflects that 🤦‍♂️

I'm slowly moving those comments into the functions. However, PyDoc documentation claims that the regular comments just above the function are also recognized, so we're not THAT far off 🤞

[snuffy22]

So the PyDoc has to be indented inside the function for pdoc to read it as least from what I saw when trying to browse output.
I had started playing in the augment folder for making more valid PyDoc info.

That being said, I am not sure how many new people would find it that useful as the website documentation explains most things.
Normally PyDoc is most useful for something that is intended to be used as API for other applications to call.

[snuffy22]

I have a branch that I am reviewing, that used ChatGPT to create/update the documentation.

I believe the augment folder is a good starting point as it has some of the core transformations that happen.
Will post a link to my branch when its ready to look at and we can decide if it is 'too much'.

Cheers

[snuffy22]

Ended up throwing away most of what it suggested as it didn't add value...

[ipspace]

Ended up throwing away most of what it suggested as it didn't add value...

Welcome to the wonderful world of AI-based coding 😜

[ipspace]

So? Close this?

[snuffy22]

I have a second attempt that I have mostly worked through..

Will put up a PR next week.

[snuffy22]

Below are the three branches with pydoc related changes.
I have standardized on the double quote style throughout.

• https://github.com/snuffy22/netlab/tree/fix-pydoc (covers augment directory)
• https://github.com/snuffy22/netlab/tree/fix-pydoc-pt2 (covers cli directory)
• https://github.com/snuffy22/netlab/tree/fix-pydoc-pt3 (currently only validate directory)

These are all firstly 'mechanical' changes to make the documentation show up in pydoc, rather than wholesale additions of new documentation.

My thoughts were to put this base change in then work on any additional updates to function descriptions.