From 281e6baf13e5bfa036717c2e6c1202b3d7d38e15 Mon Sep 17 00:00:00 2001 From: Dominik Gresch Date: Fri, 2 Feb 2024 14:06:14 +0100 Subject: [PATCH] Add scaffolding for improved documentation Add a landing page using a grid to the documentation, containing the following sections: - Getting started - How-to guides - Examples - API reference - Contributing The individual sections are still incomplete. --- CONTRIBUTING.md | 4 ++ README.rst | 10 ++- doc/source/contribute.rst | 23 +++++++ doc/source/howto/index.rst | 9 +++ doc/source/howto/launch_configuration.rst | 4 ++ doc/source/index.rst | 84 +++++++++++++++++++---- doc/source/intro.rst | 19 +++++ 7 files changed, 139 insertions(+), 14 deletions(-) create mode 100644 doc/source/contribute.rst create mode 100644 doc/source/howto/index.rst create mode 100644 doc/source/howto/launch_configuration.rst create mode 100644 doc/source/intro.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd07ed7014..b77db6d65e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing + + We absolutely welcome any code contributions and we hope that this guide will facilitate an understanding of the PyACP code repository. It is important to note that while the PyACP software @@ -9,6 +11,8 @@ support user questions and develop new features to make this software a useful tool for all users. As such, we welcome and encourage any questions or submissions to this repository. + + Please reference the [PyAnsys Developer's Guide](https://dev.docs.pyansys.com) for the full documentation regarding contributing to the PyACP project. diff --git a/README.rst b/README.rst index cdc4762879..c62684c005 100644 --- a/README.rst +++ b/README.rst @@ -108,6 +108,8 @@ Model from an existing file: >>> model.name 'ACP Model' +.. START_MARKER_FOR_SPHINX_DOCS + Development Setup ----------------- @@ -134,13 +136,15 @@ You will need to follow these steps: pipx ensurepath pipx install poetry -3. Set up credentials for the PyAnsys internal PyPI instance +3. Set up credentials for the PyAnsys internal PyPI instance .. code-block:: bash poetry config http-basic.pyansys_private_pypi TOKEN - Where `` should be replaced with the PAT for the internal PyPI instance. Reach out to a team member or the PyAnsys team for access instructions. + Where ```` should be replaced with the PAT for the internal PyPI instance. Reach out to a team member or the PyAnsys team for access instructions. + + .. TODO: REMOVE BEFORE RELEASE: this will no longer be needed once PyACP and its dependencies are public 4. Install the project and all its development dependencies using poetry. This also takes care of creating a new virtual environment: @@ -253,6 +257,8 @@ This creates both a source distribution, and a wheel file. An alternative is pip install build python -m build --wheel +.. END_MARKER_FOR_SPHINX_DOCS + License ------- ``PyACP`` is licensed under the MIT license. Please see the `LICENSE `_ for more details. diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst new file mode 100644 index 0000000000..55ef345d0f --- /dev/null +++ b/doc/source/contribute.rst @@ -0,0 +1,23 @@ +Contribute +========== + + +.. include:: ../../CONTRIBUTING.md + :start-after: + :end-before: + +For example, you could contribute by: + +- Reporting a bug or suggesting a feature +- Giving feedback or making suggestions for improving our documentation +- Submitting a pull request to fix a bug or add a feature +- Reporting your use case, and how PyACP helped you or what is still missing + +For feedback, suggestions, or bug reports, please open an `issue +`_ on our GitHub repository. +For code changes or documentation improvements, please open a `pull request +`_. + + +.. include:: ../../README.rst + :start-after: START_MARKER_FOR_SPHINX_DOCS diff --git a/doc/source/howto/index.rst b/doc/source/howto/index.rst new file mode 100644 index 0000000000..f40ee87077 --- /dev/null +++ b/doc/source/howto/index.rst @@ -0,0 +1,9 @@ +How-to guides +------------- + +These short guides are designed to illustrate one particular aspect of using PyACP. + +.. toctree:: + :maxdepth: 2 + + launch_configuration diff --git a/doc/source/howto/launch_configuration.rst b/doc/source/howto/launch_configuration.rst new file mode 100644 index 0000000000..c6797a0096 --- /dev/null +++ b/doc/source/howto/launch_configuration.rst @@ -0,0 +1,4 @@ +Changing how ACP is started +--------------------------- + +TODO diff --git a/doc/source/index.rst b/doc/source/index.rst index 0b957fdde2..dfec457b0c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,24 +1,84 @@ -.. - Just reuse the root readme to avoid duplicating the documentation. - Provide any documentation specific to your online documentation - here. - -============================= -PyACP documentation |version| -============================= - -.. include:: ../../README.rst - .. jinja:: main_toctree .. toctree:: :hidden: :maxdepth: 3 - PyACP + self + intro {% if not skip_gallery %} examples/index {% endif %} + howto/index {% if not skip_api %} api/index {% endif %} + contribute + + +PyACP +----- + +.. note:: + + PyACP is currently released as a beta version. This means that the API may + change in future releases. We encourage you to try PyACP and provide us with + feedback. + +PyACP enables modelling continuous-fiber composite structures from within your +Python environment. It provides access to the features of Ansys Composite +PrepPost (ACP) through a Python interface. + +This makes PyACP a powerful tool for automating the design, analysis and +optimization of composite structures. + +.. jinja:: main_toctree + + .. grid:: 1 1 2 2 + :gutter: 2 + + .. grid-item-card:: :octicon:`rocket` Getting started + :link: intro + :link-type: doc + + Contains installation instructions and a simple example to get you + started with PyACP. + + .. grid-item-card:: :octicon:`light-bulb` How-to guides + :link: howto/index + :link-type: doc + + Guides on how to achieve specific tasks with PyACP. + + .. grid-item-card:: :octicon:`play` Examples + {% if not skip_gallery %} + :link: examples/index + :link-type: doc + {% endif %} + + A collection of examples demonstrating the capabilities of PyACP. + + .. grid-item-card:: :octicon:`file-code` API reference + {% if not skip_api %} + :link: api/index + :link-type: doc + {% endif %} + + Describes the public Python classes, methods, and functions. + + .. grid-item-card:: :octicon:`code` Contribute + :link: contribute + :link-type: doc + :columns: 12 + + Information on how to contribute to PyACP. + +Key features +^^^^^^^^^^^^ + +TODO + +Limitations +^^^^^^^^^^^ + +TODO diff --git a/doc/source/intro.rst b/doc/source/intro.rst new file mode 100644 index 0000000000..ab9c55d0b7 --- /dev/null +++ b/doc/source/intro.rst @@ -0,0 +1,19 @@ +Getting started +--------------- + +Installation +^^^^^^^^^^^^ + +PyACP supports Ansys version 2024R2 and later. To install PyACP, run the following command: + +.. code-block:: bash + + pip install ansys-acp-core + +You should use a `virtual environment `_, +because it keeps Python packages isolated from your system Python. + +Usage +^^^^^ + +TODO