search

ansys / pymapdl

Pythonic interface to MAPDL
https://mapdl.docs.pyansys.com
MIT License
424 stars 120 forks source link

Documenting MAPDL commands with extensive command documentation #874

Open germa89 opened 2 years ago

germa89 commented 2 years ago

Description

Some commands such *GET, TB and many more have very long documentation in the command reference. I feel like, it is very long. Some Note sections cover all the possible configurations of those commands.

Definitely we are aiming to have everything very well documented. However, I wonder if a docstring is the right place for this, keeping in mind that those pages require quite a lot of manual work to make it match Sphinx requirements. Sometimes, I even feel the Sphinx tool is not even enough to cover all the possibilities the command reference offer.

Current situation

We have trimmed down the documentation to mention only the arguments, but most of the cases we don't go further.

Possible solutions.

I see two possibilities here:

Any of the options raise the problem of documentation updating. If an automated process to get the command reference info is ever in place, much of the manual work is going to be overwritten.

Issues related

774

akaszynski commented 2 years ago

Suggest separate docs page. Agree that it’s too long.

germa89 commented 2 years ago

It might be even better for later updates ... maybe I'm not sure.

dnwillia-work commented 2 years ago

I agree this is a bit awkward. The MAPDL documentation for all the commands is quite extensive and it seems a bit awkward to have to manually reproduce the content again here. Is it possible to just copy of the APDL commands help from the user documentation into a bunch of rst pages and just repost it here?

germa89 commented 2 years ago

It is possible to inject text in docstrings, we actually do it for some commands related to BC listing:

https://github.com/pyansys/pymapdl/blob/475a292a03f3fe25e6c3ef2e8d1a70aac0c730e5/src/ansys/mapdl/core/mapdl.py#L207-L244

I believe we should think on a reliable way to pass keep our docstrings updated, and very likely it is going to involve this docstring injection. Conflicts will happen when sync MAPDL info with modified function docstring (for example if we add parameters, add data input types, etc).

In addition, there have been some conversation with documentation and legal teams about publishing command reference and it seems finally it will be possible. This will allow us, using the source documentation to output some parsed docstrings which can automatize all this procedure. This is on the "thinking about it" stage, but it should probably be done in the next quarter (See PyMAPDL Roadmap https://github.com/orgs/pyansys/projects/10/views/4). Will see how much we can stretch ourselves :)

dnwillia-work commented 2 years ago

Yeah I think this will be kind of a per-product strategy in terms of how to do it but I agree. Chatting with our documentation team the idea would just be to literally copy over the content wherever it's appropriate. For all the Fluent commands we already use injection of what is coded directly inside Fluent, but the documentation team also maintains the user doc which has more content.

akaszynski commented 2 years ago

We've received confirmation that the internal XML files are now permitted to be rendered to Python.

We now need an automated way of doing that per release, noting deprecated methods, and injecting or appending our customized Examples, and Notes sections within the documentation.