Pyi integration

[evaherrada]

No description provided.

[evaherrada]

Hi @tannewt I've got it kinda passing the script you wrote (it's been working great so far). However, I do have two questions, first, it didn't pass unless there was no leading whitespace, how does this affect the python examples in the code.

Secondly, the script fails on __init__.c which doesn't have any associated stub files. What should I do about that? It always gets checked last, so I can still go through all of the other files, but I just wanted to check if there's anything I should be doing about that.

[tannewt]

Hi @tannewt I've got it kinda passing the script you wrote (it's been working great so far). However, I do have two questions, first, it didn't pass unless there was no leading whitespace, how does this affect the python examples in the code.

By removing the whitespace you are making it so the script doesn't include it in the .pyi file. (You can see the results in the circuitpython-stubs directory.) So, you aren't fixing it, you are removing it from the process.

Secondly, the script fails on init.c which doesn't have any associated stub files. What should I do about that? It always gets checked last, so I can still go through all of the other files, but I just wanted to check if there's anything I should be doing about that.

What __init__.c are you referring to? I don't see the error in your current commit.

[evaherrada]

@tannewt Ok, that makes a lot of sense. How exactly am I supposed to format the whitespace? I'm referring to any __init__.c, I'll get you the exact error message in 1 sec

[tannewt]

@tannewt Ok, that makes a lot of sense. How exactly am I supposed to format the whitespace? I'm referring to any init.c, I'll get you the exact error message in 1 sec

Every line for the stubs should start with //| and then be indented from there like a valid .pyi file.

[tannewt]

Ok, I've polished this up and switched Sphinx to using autoapi on top of the stubs.

@jepler want to do a review for merge?

[jepler]

Besides the comment, I noticed that ulab doc is empty now. ulab is an oddball, it is just a rst file rather than a source file. There's a pyi file there, but its content still looks like it's restructuredtext. The fact that this is not showing an error during doc build is worrying; if it's treating it as pyi but the content is nonsense, the build should fail.

Documentation of "math" is missing.

There's a page for "protomatter" and there shouldn't be. It was renamed rgbmatrix, which is there.

The page _build/html/shared-bindings/help.html has jumbled content.

Links from support matrix to the module pages works, yay.

Deep links into the docs will be broken, but so be it.

As far as ulab goes, we should also check with v923z whether he wants pyi files upstream, though we can do that second and move the file out if desired. Originally he was not interested in adapting his documentation to CPy standards (which is fine), but we should make an overture anyhow. But that assumes the ulab doc is put into shape first.

[tannewt]

Besides the comment, I noticed that ulab doc is empty now. ulab is an oddball, it is just a rst file rather than a source file. There's a pyi file there, but its content still looks like it's restructuredtext. The fact that this is not showing an error during doc build is worrying; if it's treating it as pyi but the content is nonsense, the build should fail.

I made the script error correctly and then fixed up ulab.

Documentation of "math" is missing.

Fixed!

There's a page for "protomatter" and there shouldn't be. It was renamed rgbmatrix, which is there.

I don't see that on my local copy.

The page _build/html/shared-bindings/help.html has jumbled content.

Looks like a rogue copyright header.

Links from support matrix to the module pages works, yay.

Deep links into the docs will be broken, but so be it.

We do have the ability to load a bunch of redirects into ReadTheDocs if need-be. https://docs.readthedocs.io/en/stable/user-defined-redirects.html

As far as ulab goes, we should also check with v923z whether he wants pyi files upstream, though we can do that second and move the file out if desired. Originally he was not interested in adapting his documentation to CPy standards (which is fine), but we should make an overture anyhow. But that assumes the ulab doc is put into shape first.

@v923z See the .pyi files I added.

[jepler]

Thanks for addressing my comments!

[tannewt]

Ok, removed the debug prints.

[jepler]

thanks

[v923z]

As far as ulab goes, we should also check with v923z whether he wants pyi files upstream, though we can do that second and move the file out if desired. Originally he was not interested in adapting his documentation to CPy standards (which is fine), but we should make an overture anyhow. But that assumes the ulab doc is put into shape first.

I am a bit late to the party, but here are my comments. A second movement, if you wish, since @jepler started out with the overture.

1. I generate the ulab documentation from a jupyter notebook for the reason that that is the simplest (and perhaps, most elegant) way of running code in the documentation itself.

2. At the moment the user manual itself is an rst file, nothing more. That is the result of the conversion of the jupyter notebook.

3. The manual is actually a bit more than a description of the function signatures: it contains benchmarks, a number of hints as to how to efficiently use the functions, and what the gains are. As such, it is probably the most relevant and valuable contribution, at least, in the specific context of a microcontroller.

Having said these, I am not against change. I brought up this issue at the very beginning, with the argument that a single source would reduce the documentation effort.

I could probably part with the jupyter notebook, but I would definitely like to retain what was mentioned in the third point. If we can come up with a reasonable scheme that is acceptable to all concerned, I will not stand in the way.