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.
ansys · Feb 2, 2024 · 281e6ba · 281e6ba
1 parent 7ca4ea3
commit 281e6ba
Show file tree

Hide file tree

Showing 7 changed files with 139 additions and 14 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,7 @@
 # Contributing
 
+<!-- START_MARKER_FOR_SPHINX_DOCS -->
+
 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.
 
+<!-- END_MARKER_FOR_SPHINX_DOCS -->
+
 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
@@ -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 <TOKEN>
 
-    Where `<TOKEN>` 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 ``<TOKEN>`` 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 <https://github.com/ansys-internal/pyacp/raw/main/LICENSE>`_ for more details.

diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst
@@ -0,0 +1,23 @@
+Contribute
+==========
+
+
+.. include:: ../../CONTRIBUTING.md
+    :start-after: <!-- START_MARKER_FOR_SPHINX_DOCS -->
+    :end-before: <!-- END_MARKER_FOR_SPHINX_DOCS -->
+
+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
+<https://github.com/ansys-internal/pyacp/issues>`_ on our GitHub repository.
+For code changes or documentation improvements, please open a `pull request
+<https://github.com/ansys-internal/pyacp/pulls>`_.
+
+
+.. include:: ../../README.rst
+    :start-after: START_MARKER_FOR_SPHINX_DOCS
diff --git a/doc/source/howto/index.rst 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
@@ -0,0 +1,4 @@
+Changing how ACP is started
+---------------------------
+
+TODO
diff --git 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>
+        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
@@ -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 <https://docs.python.org/3/library/venv.html>`_,
+because it keeps Python packages isolated from your system Python.
+
+Usage
+^^^^^
+
+TODO