Documentation

[gswifort]

I plan to start working on (at least) basic documentation, using Sphinx.

[CEXT-Dan]

Cool! What did he have before? Maybe pydoc. I had tried Sphinx when I first started the project; I couldn’t get it to work with embedded

[gswifort]

I don't understand the question. Sphinx actually needs the python source code. From what I've read so far, it doesn't even support *.pyi files, but it's probably enough to copy them to a temporary directory with the .py extension for the generation time. These are my first steps in this area, I've never used any framework to create documentation.

[CEXT-Dan]

I don't understand the question

I had the HTML doc in the original doc string generator. I think the problem was is had the C++ signatures

import pydoc
def generate_html_help(moduleName, module):
    str = pydoc.html.docmodule(module)
    with open(moduleName, mode='w') as f:
	    print(str, file=f)

good idea to use the stubs!

[gswifort]

I will develop it on a separate branch because it is a long task. I will also need your help. I understand that switching branches is not a problem if you do not have to compile on them?

[CEXT-Dan]

I will develop it on a separate branch

Yeah, its no problem.

[rdesparbes]

I plan to start working on (at least) basic documentation, using Sphinx.

Another modern alternative to be aware of is MkDocs. It uses Markdown by default, which is a bit less cumbersome to use than reStructuredText in my opinion.

An example of documentation built with MkDocs: https://fastapi.tiangolo.com/

[gswifort]

Thanks! I'll look into it.

[rdesparbes]

If we do not like reStructuredText we can also use Sphinx with the MyST plugin

[CEXT-Dan]

Documentation is a task that can be measure in man years. So big in fact that BricsCAD, ZwCAD, and GStarCad just generate class hierarchies with functions. We had the same once, it was useful in that it listed and categorized the classes and functions

Do we need more? If so, what is our plan?

• what is the file format?
• where is it hosted?
• AutoCAD has offline documentation that can be plugged directly in Visual Studio. Is there some extension in vscode or pycharm that can do this? If so, what is the file format?

Many hands make light work;

how can users contribute to the documentation? As of now, the master help is inside an SQLite database, the idea at the time was I could plug in a row index in the C++ source. This became a problem when doing BricsCAD stuff because BricsCAD won’t load Python’s SQLite, so I started exporting to JSON. How can this be improved to make it easily accessible while maintaining the unique row ids?

• Legality, I scraped Autodesk’s help
  https://creativecommons.org/licenses/by-nc-sa/3.0/
  https://www.autodesk.com/company/creative-commons
  at the least, I see “You must give appropriate credit”, lets make sure we do this
  is it okay we republish their help? (I assume so, but...)

I think it should be well thought out this time around

[gswifort]

Yes, it's a lot of work. At first I wanted to focus on how PyRx works, not ARX - i.e. installation (different scenarios), basic usage examples, known issues, FAQ. All of this basically appears somewhere, a bit in README, a bit in discussions, but it's worth structuring. Of course I also thought about documenting all the functions, but more as a class hierarchy with links to Autodesk documentation.

[gswifort]

• where is it hosted?

https://readthedocs.com/

[CEXT-Dan]

Oh cool, free for opensource!

[gswifort]

I have two motivations for this:

1. I want more people to be interested in this project, basic documentation can help with that
2. I have never created professional documentation before

[schoeller]

@gswifort 👍
I very much appreciate this initiatize. To my background: I am more of an occasional user with some Python skills. If content is generated I may cross-read from this perspective whenever time permits.

What I personally would be very much interested is a sample structure for a project. I have tried something in repeating samples copying parts of the BRXSDK. Let's say one was a user to manage and extend a command collection or even an entire custom ribbon set, it would be awfully helpful to peek into the code structure of a PyRx Python pro how they would approach the task.

[gswifort]

Sorry, I haven't had much time to work on this lately, but I'd really like to create a sample project with a build and installer. I hope to be able to do that soon.

[gswifort]

@schoeller @CEXT-Dan
https://github.com/gswifort/PyRx-sample-project

[CEXT-Dan]

Nice! I haven’t tried it yet, but should we put a link on the front page so it’s more visible?

[gswifort]

Yes of course