Improve documentation layout

[jorgepiloto]

🐞 Problems

Writing documentation is tedious. Without a proper layout, adding or modifying existing guidelines may become a serious problem. After reviewing in deep the current status of the developers guidelines, I experienced the following problems:

• It is difficult to find information: it is there, but not well organized.

• Existence of duplicated sections: this is a consequence of previous situation.

  • Development practices/Creating a PR overlaps with Documentation practices/Creating a PR
  • Library Overview/Setup File, Library Overview/README File, Library Overview/License File could be unified with Library Overview/Required Files
  • See New Packaging Style guide #62 for more examples.
  • We have kind of duplicated issues too, see Adding a section regarding packaging #21 and Add python packaging approaches #25

• Lack of topics.

  • Setting up a developer environment: Python, venv, Git, IDE... We could use sphinx tabs for supporting Windows, MacOS, and Linux commands.
  • Why pyproject.toml? Related with Add python packaging approaches #25
  • Configure Git, signing commits and using SSH.

💡 Suggested Solution

Using the recently published Docs for Developers and the popular talk What nobody tells you about documentation, the following structure could be used for the PyAnsys Developers Guide.

• How-To
  • All guidelines and step-by-step tutorials for achieving a given goal.
• Packaging Style
  • For packaging a project.
• Coding Style
  • Anything about code style, minimum style requirements, available formatting tools...
• Doc style
  • Anything about docstring style, API doc layout, doc formatting tools...
• Abstractions
  • Theoretical knowledge. Not a "how-to", just explanations on fundamental PyAnsys topics.

[akaszynski]

It is difficult to find information: it is there, but not well organized.

Quite right, and having a fresh set of eyes to look at this is quite helpful. Issue is that we've had several developers (including myself) add sections over time, and these sections are often nested within other sections. I recall once looking for a section I wrote myself and couldn't even find it; I had to search for it.

Lack of topics.

100% agree with sphinx tabs. That's helpful when letting users know about options/choices when selecting between several options without overwhelming them with a laundry list or long document.

Suggested Solution...

Agree with the refactor. Recommend that you first reorganize and then rewrite by topic.

[jorgepiloto]

Linking here ansys/ansys-templates#39 since ansys-templates documentation points to a Contributing section which will be created when implementing this.

[jorgepiloto]

We should avoid as much as possible the usage of underscore (and even dashes) in the page URL. Some arguments supporting this are:

• Simple and easy to remember URLs
• Dashes are considered to be separators while underscores join terms. See This video from Google Search Central

The slug of the page gets auto-generated according to the name of the directories and the RST file. Some of these directories hold dashes and underscores. This is the origin of those symbols in the current dev guide.

This is not a big problem but we could take advantage of this refactor proposal to apply this changes.

[jorgepiloto]

I just remembered about this extension: https://github.com/executablebooks/sphinx-external-toc