Fix documentation compilation

[thierry-martinez]

@shinich1 noticed that documentation compilation was broken (see comment). This pull request fixes examples, cross-references and doc-comments to fix various errors. Another commit adds a doc workflow for CI validation of the documentation (as suggested by @EarlMilktea, #198 (comment)).

I used sphinx-build --nitpicky first to catch more errors, but I didn't manage to make it resolve references to nx_reportviews.EdgeView, so I removed the option.

[shinich1]

great PR, thanks!

[EarlMilktea]

@thierry-martinez

Read the Docs has the official CI framework: https://docs.readthedocs.io/en/stable/integrations.html (you can see the deployment/errors via GUI like this: https://readthedocs.org/projects/cupy/builds/25317461/ )
Why not use it?

[thierry-martinez]

We could configure Read the Docs CI, but the integration with GitHub seems to require admin rights on both sides (GitHub and Read the Docs). On the other hand, I was able to add the doc workflow without needing admin rights on either platform.

What are the benefits of using Read the Docs CI instead of GitHub Actions?

Perhaps we could merge this PR first since it fixes a number of errors and the CI check with GitHub Actions is working properly. We could then propose using Read the Docs CI in a separate issue or PR, where someone with admin rights can handle the setup. What do you think?

[EarlMilktea]

Either looks good to me.

[EarlMilktea]

Related to package documentation/comment, let me suggest an idea: why not use Ruff rule D for better documentation styling?
We may need to turn off D10 for now to allow undocumented public items.

[shinich1]

Perhaps we could merge this PR first since it fixes a number of errors and the CI check with GitHub Actions is working properly. We could then propose using Read the Docs CI in a separate issue or PR, where someone with admin rights can handle the setup. What do you think?

I think we can merge this PR after adding D rule as @EarlMilktea suggested. We should explore github pages which might integrate better with github actions.

[EarlMilktea]

Memo: May need to completely ignore rule D for examples/*.py.

[thierry-martinez]

I turned on the D rule in fd1c57c, and add/fixed the docstrings. D rule is ignored in benchmarks, examples and tests.

[EarlMilktea]

@thierry-martinez

How thorough it is! Excellent!
Let me suggest some additional fixes on https://github.com/TeamGraphix/graphix/tree/fix-doc-ss .

[EarlMilktea]

MEMO: Opened #208 to speed up CI checks.

[thierry-martinez]

If there's anything else I should address before merging, please let me know!

[EarlMilktea]

Great! Only some minor suggestions.

[shinich1]

@thierry-martinez LGTM! please squash and merge after resolving conflict, if you think it's ready?