API doc restructuring latest

[hpohekar]

--------------------------------------------------------------------------------------------------------------------

[seanpearsonuk]

@hpohekar

I did the following:

• I downloaded the html from the doc build
• I go to the API ref - OK
• Go to launcher - OK
• Go to return types of launch_fluent - OK
• Click on Solver - OK

All good to this point

• In Solver page, I click on e.g., file, which takes me to the plain file property of Solver. Ideally, these we want to link to the actual API objects. Are we able to establish those connections?

[seanpearsonuk]

@hpohekar

Here https://fluent.docs.pyansys.com/dev/api/solver/settings.html#ref-settings , the root object at the bottom of the page is no longer clickable as it was in previous versions. Also, in the html built in your branch. Do we no longer have any settings API doc?

[hpohekar]

@hpohekar

I did the following:

• I downloaded the html from the doc build
• I go to the API ref - OK
• Go to launcher - OK
• Go to return types of launch_fluent - OK
• Click on Solver - OK

All good to this point

• In Solver page, I click on e.g., file, which takes me to the plain file property of Solver. Ideally, these we want to link to the actual API objects. Are we able to establish those connections?

API ref -> General - > Sessions -> session_solver -> Solver -> file -> class ansys.fluent.core.session_solver.Solver.file

---------------------------------------------------------

API ref -> Meshing -> meshing.tui -> meshing.tui.file -> class main_menu.file

API ref -> Solver-> solver.tui -> solver.tui.file -> class main_menu.file

In case of solver file is property and in case of TUI file is a class.

Due to this difference inter sphinx mapping is not useful here hence we are not able to establish those connections.

[hpohekar]

@hpohekar

Here https://fluent.docs.pyansys.com/dev/api/solver/settings.html#ref-settings , the root object at the bottom of the page is no longer clickable as it was in previous versions. Also, in the html built in your branch. Do we no longer have any settings API doc?

@seanpearsonuk

Right, we have removed root due to it's nested structure.

To get above thing clickable we will have to use root without table structure and clickable return types because it takes huge time to generate docs for all nested classes.

settings are not deployed yet, we are resolving issues related settings because it is failing due to it's large size by giving parallel build error.

[dnwillia-work]

@hpohekar
Here https://fluent.docs.pyansys.com/dev/api/solver/settings.html#ref-settings , the root object at the bottom of the page is no longer clickable as it was in previous versions. Also, in the html built in your branch. Do we no longer have any settings API doc?

@seanpearsonuk

Right, we have removed root due to it's nested structure.

To get above thing clickable we will have to use root without table structure and clickable return types because it takes huge time to generate docs for all nested classes.

settings are not deployed yet, we are resolving issues related settings because it is failing due to it's large size by giving parallel build error.

If we only generated code for the settings that have proper help strings I bet it would be a bunch smaller.

[dnwillia-work]

Downloaded the documentation artifact and had a look:

• The main landing page for the API reference has three headings, General, Meshing and Solver. They are a bit big and should contain some descriptions of the content to which they link as they do on the current landing page. The reference links on the right do not seem to be working for me, they just show up as gray boxes with "ref_general", "ref_meshing" and "ref_solver" contained within, clicking on them does not work.
• When I click on General, Meshing or Solver on the main landing page it takes me to the corresponding sub-landing page. These pages have the same issue. No descriptive introductory content for the sub-modules, the reference links on the right are not working.
• I see there is an 'rpvars' module. Is that on purpose? I don't think we should document this.
• The numpydoc strings do not always appear for the various classes and functions. For instance, I cannot find this string in the generated doc: https://github.com/pyansys/pyfluent/blob/d24a562332300579a83c4f58be228c7e792c5fd7/src/ansys/fluent/core/scheduler/load_machines.py#L19
• The title for the case reader section is "Use case reader" I think it should just be "Case reader".
• The module documentation for the 'journal' module says "Module for maintaining journal.". It's not quite proper grammar, should maybe be "A module for maintaining journals."
• Another example of a docstring that does not appear: https://github.com/pyansys/pyfluent/blob/d24a562332300579a83c4f58be228c7e792c5fd7/src/ansys/fluent/core/quantity.py#L837

It seems the PR still needs a fair bit of tidy up... this is just what I spotted clicking through it for 5 min.

[hpohekar]

Downloaded the documentation artifact and had a look:

• The main landing page for the API reference has three headings, General, Meshing and Solver. They are a bit big and should contain some descriptions of the content to which they link as they do on the current landing page. The reference links on the right do not seem to be working for me, they just show up as gray boxes with "ref_general", "ref_meshing" and "ref_solver" contained within, clicking on them does not work.
• When I click on General, Meshing or Solver on the main landing page it takes me to the corresponding sub-landing page. These pages have the same issue. No descriptive introductory content for the sub-modules, the reference links on the right are not working.
• I see there is an 'rpvars' module. Is that on purpose? I don't think we should document this.
• The numpydoc strings do not always appear for the various classes and functions. For instance, I cannot find this string in the generated doc: https://github.com/pyansys/pyfluent/blob/d24a562332300579a83c4f58be228c7e792c5fd7/src/ansys/fluent/core/scheduler/load_machines.py#L19
• The title for the case reader section is "Use case reader" I think it should just be "Case reader".
• The module documentation for the 'journal' module says "Module for maintaining journal.". It's not quite proper grammar, should maybe be "A module for maintaining journals."
• Another example of a docstring that does not appear: https://github.com/pyansys/pyfluent/blob/d24a562332300579a83c4f58be228c7e792c5fd7/src/ansys/fluent/core/quantity.py#L837

It seems the PR still needs a fair bit of tidy up... this is just what I spotted clicking through it for 5 min.

@dnwillia-work @seanpearsonuk

Yes sure. Until now we were focused on resolving all issues related to API doc generation and right now we are able to generate it successfully.

So now onwards we will focus on description, heading, titles, fonts etc.

Thank you.

[hpohekar]

@dnwillia-work @h-krishnan

In CI we are generating only source code docs.

We can download the unified (Source code + datmodel + TUI + settings) doc artifact from here -

https://github.com/pyansys/pyfluent/actions/runs/4366541276

Thank you.