Docs/content writing

[PipKat]

@RobPasMue This draft PR is to incorporate the content initially drafted as the *PyAnsys writer's guide" into the *PyAnsys developer's guide". As per your recommendation, we can reorganize/consolidate content once the two guides are combined.

Note that I had added a central "links.rst" file, which required having to remove lots of duplicated explicit target names. This central file should also be reorganized later. (I can also reorganize the Vale action and structure later, either in this PR or another one.)

I built the documentation locally fine. However, I am seeing the following "Documentation style" check error, which I don't know how to resolve and will need your help with:

Error: reviewdog: Too many results (annotations) in diff. Error: reviewdog: Too many results (annotations) in diff.
You may miss some annotations due to GitHub limitation for annotation created by logging command.
Please check GitHub Actions log console to see all results.

[RobPasMue]

Hi @PipKat - thanks for opening this PR! Really appreciated =) I'll try to fix your issue asap

[RobPasMue]

All looks good to me - my only recommendation is that instead of using underscores for folders and file names, it is better to use hyphens as separators. All files in this repo are using them. Could you adapt @PipKat ?

[wiz-inc-572fc38784]

Wiz Scan Summary

IaC Misconfigurations
Vulnerabilities
Sensitive Data
Total
Secrets

[RobPasMue]

OKay so they are mostly warnings. Have a look at some of them like the usage of "we,our...". Others, just ignore them. I made the vale checks to be an independent stage. That way we can verify that the docs build on CI/CD at least. Once merged, the warnings will be ignored in upcoming PRs.

[RobPasMue]

Seems like there are some warnings as well (in the build process): https://github.com/ansys/pyansys-dev-guide/actions/runs/8277223778/job/22647164814#step:4:2846

Could you handle them @PipKat ? If you need help let me know!

[PipKat]

Seems like there are some warnings as well (in the build process): https://github.com/ansys/pyansys-dev-guide/actions/runs/8277223778/job/22647164814#step:4:2846

Could you handle them @PipKat ? If you need help let me know!

@RobPasMue Those uses of "we" and "our" are intentional in the "Content writing" section to show what not to do! I'll try to resolve the broken links and other issues though--and fix the naming to use hyphens. Thanks.

[RobPasMue]

@RobPasMue Those uses of "we" and "our" are intentional in the "Content writing" section to show what not to do! I'll try to resolve the broken links and other issues though--and fix the naming to use hyphens. Thanks.

If they are intentional then we might want to deactivate vale in that section =) See https://vale.sh/docs/topics/config/#restructuredtext

[PipKat]

@RobPasMue I'm still tracking down 8 more duplicated explict target names. As @germa89 can tell you, this is a long and painful process. When using a central "links.rst" file, you can't use the explicit link more than once on any given page. (Or at least this is how I remember it from working on a "links.rst" file for what was the PyAnsys writer's guide. I've copied @germa89 because I believe he may have posted an issue or might have since come up with a different solution. I'll work more on this tomorrow.

[PipKat]

@RobPasMue Those uses of "we" and "our" are intentional in the "Content writing" section to show what not to do! I'll try to resolve the broken links and other issues though--and fix the naming to use hyphens. Thanks.

Turns out all those "we" and "ours" were in comments in code blocks. I removed them--but I didn't think Vale checked anything in code blocks!

[RobPasMue]

Working on some attempts on my side

[RobPasMue]

Looks like the duplicate link issue/target is now fixed :)

[PipKat]

@RobPasMue The "Build project documentation" check now passes, and all files and folders that I added use hyphens rather than underscores as separators in folder and file names. (Note that there are older files in this repository where underscores are still used. I didn't want to touch these pre-existing files because I wasn't as familiar with them.)

I thought it might be best to get this PR, which is just to get my initial PyAnsys writer's guide content incorporated in its own "Content writing" section, reviewed and merged. We can then create PRs for additional tasks, such as reorganizing the central links.rst file and renaming the explicit target names within this file to be more descriptive so that they are easier to reuse. Long term, I think we should consider having a "GitHub" subsection in the "Getting started" section, with information on joining GitHub and Ansys GitHub accounts and also on setting up both development environments and content contribution environments (and maybe even a testing environment although the environment needed by a developer or tester are probably the same one). We might possibly want to move/integrate my new "Content writing" section into the existing "Documentation style" section (though the number of levels supported by the toctree will probably have to be increased). We also have to visit my "Content in Examples" section because it's really rough and incomplete. Feel free to tweak these ideas and add others to an issue that you assign to me!

[RobPasMue]

Thanks for integrating this @PipKat! I agree, let's merge this as is and do follow-up PRs and issues later on to properly integrate your content with the rest of the guide. At least, as it is, it now lives in the same site which was our first goal. Thanks again fro your hard work on this! The content is great!