diff --git a/doc/source/getting_started/contributing.rst b/doc/source/getting_started/contributing.rst index 1f7ac56da0..72e1bc3e9c 100644 --- a/doc/source/getting_started/contributing.rst +++ b/doc/source/getting_started/contributing.rst @@ -4,38 +4,90 @@ Contributing ============ +There are several ways to contribute to PyDPF-Core: + +- :ref:`ref_contributing_answer_discussions` +- :ref:`ref_contributing_post_issues` +- :ref:`ref_contributing_develop_code` +- :ref:`ref_contributing_improve_doc` + Overall guidance on contributing to a PyAnsys repository appears in -`Contribute `_ -in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar -with this guide before attempting to contribute to PyDPF-Core. - +`Contributing `_ in the *PyAnsys Developer's Guide*. +Ensure that you are thoroughly familiar with this guide before attempting +to contribute to PyDPF-Core. + The following contribution information is specific to PyDPF-Core. -Clone the repository --------------------- -Clone and install the latest version of PyDPF-Core in -development mode by running this code: +.. _ref_contributing_answer_discussions: -.. code:: +Answer discussions +------------------ + +Answering discussions is an excellent way to contribute to PyDPF-Core, and it does not require +any setup, just a GitHub account. Engaging in discussions often requires a thorough grasp of +the project’s goals and challenges. Your contributions can help other users or contributors who may be +facing similar issues, making the repository more welcoming and inclusive. By providing answers or solutions, +you can directly contribute to the project’s success, maintain its health, and encourage a positive, +open source ecosystem. - git clone https://github.com/ansys/pydpf-core - cd pydpf-core - pip install -e . +To discover how you can help see the `PyDPF-Core Discussions page `_. +.. _ref_contributing_post_issues: Post issues ----------- -Use the `PyDPF-Core Issues `_ -page to submit questions, report bugs, and request new features. -To reach the project support team, email `pyansys.core@ansys.com `_. +Posting issues in a repository allows you to voice concerns, suggest improvements, or report bugs, which can +lead to a more robust and user-friendly project. It also offers an opportunity for you to engage with the +project’s community, learn from others, and gain experience in issue tracking and collaboration. + +For the repository, issues serve as a structured way to track and prioritize work, helping maintainers understand +the needs of users and guide the project’s development. + +Use the `PyDPF-Core Issues page `_ to submit questions, report bugs, and request new features. When possible, use +these issue templates: + +- 🐞 Bug, problem, or error: Fill a bug report here; +- πŸ“– Documentation issue: Modifications to the documentation only; +- πŸŽ“ Adding an example: Proposing a new example for the library; +- πŸŽ“ Adding an tutorial: Proposing a new tutorial for the library; +- πŸ’‘ New feature: Enhancements to the code; +- If your issue does not fit into one of these categories create a blank issue. + +To reach the project support team, email `pyansys.core@ansys.com `_ + +.. _ref_contributing_develop_code: + +Develop code +------------ + +You can help improve PyDPF-Core by fixing a bug. To do it, you must set up the repository on your local +machine as per the explanations in the :ref:`ref_write_code` section. + + +.. _ref_contributing_improve_doc: + +Improve documentation +--------------------- + +The PyDPF-Core documentation plays a pivotal role in making the project more accessible and usable. +Clear and comprehensive documentation empowers users and developers to understand, implement, and +troubleshoot the project effectively. It minimizes barriers to entry, making it easier for newcomers +to get involved and for existing contributors to be more productive. + +Good documentation also reduces the burden on maintainers, as it can answer common questions and +help prevent issues. By creating or improving documentation, you not only enhance the project’s quality but +also facilitate knowledge sharing and community growth, making your contribution invaluable for the project’s +long-term success. + +To contribute on our current documentation go to the :ref:`ref_write_doc` section. + +.. toctree:: + :maxdepth: 2 + :hidden: + + write_doc/index.rst + write_code/index.rst + -View documentation ------------------- -Documentation for the latest stable release of PyDPF-Core is hosted at -`PyDPF-Core Documentation `_. -In the upper right corner of the documentation's title bar, there is an option -for switching from viewing the documentation for the latest stable release -to viewing the documentation for the development version or previously -released versions. diff --git a/doc/source/getting_started/install.rst b/doc/source/getting_started/install.rst index 3e14ed4543..2abc71fb14 100644 --- a/doc/source/getting_started/install.rst +++ b/doc/source/getting_started/install.rst @@ -7,7 +7,7 @@ Installation Install using ``pip`` --------------------- -The standard package installer for Python is `pip `_. +The standard package installer for Python is `pip `_. To use PyDPF-Core with Ansys 2022 R2 or later, install the latest version with this command: @@ -16,7 +16,7 @@ with this command: pip install ansys-dpf-core -PyDPF-Core plotting capabilities require to have `PyVista `_ installed. +PyDPF-Core plotting capabilities require to have `PyVista `_ installed. To install PyDPF-Core with its optional plotting functionalities, use: .. code:: @@ -52,7 +52,7 @@ Install without internet If you are unable to install PyDPF-Core on the host machine using ``pip`` due to network isolation, download the wheelhouse corresponding to your platform and Python interpreter version -for the latest release of PyDPF-Core from the assets section of the `latest PyDPF-Core release on GitHub `_. +for the latest release of PyDPF-Core from the assets section of the `latest PyDPF-Core release on GitHub `_. The wheelhouse is a ZIP file containing Python wheels for all the packages PyDPF-Core requires to run. To install PyDPF-Core using the downloaded wheelhouse, unzip the wheelhouse to a local directory, @@ -64,8 +64,8 @@ then use the following command from within this local directory: Beware that PyDPF-Core wheelhouses do not include the optional plotting dependencies. To allow for plotting capabilities, also download the wheels corresponding to your platform and Python interpreter version -for `PyVista `_ and -`matplotlib `_, then place them in the same previous local directory and run the command above. +for `PyVista `_ and +`matplotlib `_, then place them in the same previous local directory and run the command above. Install in development mode diff --git a/doc/source/getting_started/write_code/index.rst b/doc/source/getting_started/write_code/index.rst new file mode 100644 index 0000000000..3a2be65a40 --- /dev/null +++ b/doc/source/getting_started/write_code/index.rst @@ -0,0 +1,61 @@ +.. _ref_write_code: + +============ +Develop code +============ + +You can help improve PyDPF-Core by fixing a bug. To do it, you must set up the repository +on your local machine as per the following steps: + +- :ref:`ref_write_code_install` +- :ref:`ref_write_code_clone` +- :ref:`ref_write_code_check_install` +- :ref:`ref_write_code_develop_code` + +.. _ref_write_code_install: + +Install the repository and the DPF server +----------------------------------------- + +Install the PyDPF-Core repository by following the steps in :ref:`installation` and :ref:`ref_dpf_server`. + +.. _ref_write_code_clone: + +Clone the repository +-------------------- + +Before cloning the PyDPF-Core repository, you must install a version control system such as Git. + +Then, clone the latest version of PyDPF-Core in development mode (using ``pip`` with the ``-e`` +development flag) by running this code: + +.. code:: + + git clone https://github.com/ansys/pydpf-core + cd pydpf-core + pip install -e . + +.. _ref_write_code_check_install: + +Check the installation +---------------------- + +Run the following Python code to verify your PyDPF-Core installation: + +.. code:: + + from ansys.dpf.core import Model + from ansys.dpf.core import examples + model = Model(examples.find_simple_bar()) + print(model) + +.. _ref_write_code_develop_code: + +Develop the PyDPF-Core code +--------------------------- + +Overall guidance on contributing to the code of a PyAnsys repository appears in +`Contributing `_ in the *PyAnsys Developer's Guide*. + +You must also follow the `Coding style `_ guide to ensure +that all source code looks the same across the project. \ No newline at end of file diff --git a/doc/source/getting_started/write_doc/guidelines_tutorials.rst b/doc/source/getting_started/write_doc/guidelines_tutorials.rst new file mode 100644 index 0000000000..5dab294284 --- /dev/null +++ b/doc/source/getting_started/write_doc/guidelines_tutorials.rst @@ -0,0 +1,693 @@ +.. _ref_guidelines_tutorials: + +================= +Writing tutorials +================= + +You can improve the PyDPF-Core documentation by adding a: + +- :ref:`New tutorials section`; +- :ref:`New tutorial`. + +To do so, you must follow the guidelines presented here. + +You also need to understand the structure of the ``doc`` directory on the PyDPF-Core library: + +.. code-block:: + + . + β”œβ”€β”€ doc + β”‚ β”œβ”€β”€ source + β”‚ β”‚ β”œβ”€β”€ api + β”‚ β”‚ β”œβ”€β”€ examples + β”‚ β”‚ β”œβ”€β”€ getting_started + β”‚ β”‚ β”œβ”€β”€ images + β”‚ β”‚ β”œβ”€β”€ user_guide + β”‚ β”‚ β”œβ”€β”€ conf.py + β”‚ β”‚ β”œβ”€β”€ index.rst + β”‚ β”œβ”€β”€ styles + β”‚ β”œβ”€β”€ make.bat + + +Tutorials are located in the ``doc/source/user_guide`` directory. + +.. _ref_guidelines_add_new_tutorial_section: + +============================= +Adding a new tutorial section +============================= + +:download:`Download the new tutorial section template` + +.. note:: + + Avoid creating new folders unless absolutely necessary. + When in doubt, mention the location of the new section in the pull request for approval. + If you must create a new folder, make sure to add an ``index.rst`` file with a reference, a title, and a description of the section. + The documentation ignores folders lacking this file. + +Location and naming +------------------- + +The new tutorial section must reside in a new folder such as ``doc/source/user_guide/tutorials/new_section_name``. + +.. code-block:: + + . + β”œβ”€β”€ doc + β”‚ β”œβ”€β”€ source + β”‚ β”‚ β”œβ”€β”€ user_guide + β”‚ β”‚ β”‚ β”œβ”€β”€ tutorials + β”‚ β”‚ β”‚ β”œβ”€β”€ new_section + +Structure +--------- + +The section folder must contain an ``index.rst`` file with: + +- a reference tag for referencing this section in other parts of the documentation, +- a title for the tutorial section, +- a general description of the topics covered in the tutorials in this section, +- cards with links to the tutorials, titles, descriptions and applicable solvers, +- a ``Toctree`` for the tutorials in the section to appear in the navigation pane. + +.. literalinclude:: tutorial_section_template.rst + +You must reference the new section ``index.rst`` file in the main user guide page toctree +for it to appear in the sidebar of the user guide main page. You can find this toctree +at the end of the ``doc/source/user_guide/index.rst`` file. +For example: + +.. code-block:: + + .. toctree:: + :maxdepth: 2 + :hidden: + :caption: Tutorials + + tutorials/section_x/index.rst + tutorials/section_y/index.rst + tutorials/section_z/index.rst + tutorials/new_section/index.rst + +.. _ref_guidelines_add_new_tutorial: + +===================== +Adding a new tutorial +===================== + +:download:`Download the tutorial card template` +:download:`Download the tutorial structure template` +:download:`Download the tutorial content formating template` + +Location and naming +------------------- + +New tutorials correspond to new ``.rst`` files in tutorial section folders, +for example: ``doc/source/user_guide/tutorials/section/new_tutorial.rst`` + +.. code-block:: + + . + β”œβ”€β”€ doc + β”‚ β”œβ”€β”€ source + β”‚ β”‚ β”œβ”€β”€ user_guide + β”‚ β”‚ β”‚ β”œβ”€β”€ tutorials + β”‚ β”‚ β”‚ β”œβ”€β”€ section + β”‚ β”‚ β”‚ β”œβ”€β”€ new_tutorial.rst + +You must also add a new card in the ``index.rst`` file for the tutorial section as well as modify +its toctree. The card must include: + +- a tutorial title, +- a short description, +- badges for the applicable solvers, +- a link (in this case, the reference tag) to the tutorial file. + +.. topic:: Card example + + .. card:: Tutorial title + :text-align: center + :width: 25% + + Short description of the tutorial + + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` + +Structure +--------- + +The tutorial is divided in two main parts: + +- :ref:`Preamble` +- :ref:`Content` + +.. _ref_guidelines_tutorial_header: + +Header +^^^^^^ + +This first part is essential for clarity, organization and usability of the tutorial. It establishes the purpose +of the tutorial, making it easier to understand what is going to be explained and reference it within the other parts of +the documentation. + +The header must have : + +- a reference tag, +- a tutorial title, +- any substitution text for references to the PyDPF-Core library used in the tutorial, +- a short description (same as for the tutorial card in the tutorial section), +- an introduction, +- download buttons for Python script and Jupyter notebook versions of the tutorial. + +.. literalinclude:: tutorial_structure_template.rst + :end-before: First Step + +The main PyDPF-Core library references are available in the ``doc/source/links_and_refs.rst`` file. +To add a reference, use the substitution text as usual: + +.. code-block:: + + .. _ref_tutorial_template: + + + ============== + Tutorial title + ============== + + Here some text. Here we use the |MeshedRegion| substitution text + +For more information about the predefined references, see the +:download:`links and references file <../../links_and_refs.rst>`. + +.. _ref_guidelines_tutorial_content: + +Content +^^^^^^^ + +The goal of a tutorial is to present a feature or explain how to perform a common task step by step while explaining a behavior or underlying concepts. +Thus, its structure must prioritize clarity, simplicity, and logical flow. + +Sections +~~~~~~~~ + +A well-organized tutorial breaks down complex tasks into manageable steps, presenting information incrementally +to avoid overwhelming the user. It combines concise explanations with actionable instructions, ensuring users +can follow along easily while building their understanding. + +Thus, the sections of the content are the steps themselves. These steps are generally similar to: + +#. A first step where you get some data and create DPF objects based on the data; +#. One or more steps where you manipulate the data or the DPF objects; +#. A final step where you reach the objective of the tutorial and obtain the expected result. + +For example: + +A tutorial explains how to plot a mesh using PyDPF-Core. +The steps to achieve this task are: + +#. Import a result file; +#. Extract the mesh; +#. Plot the mesh. + +To create those section, underline it with the appropriate characters (here: ``-``). + +.. code-block:: + + Import result file + ------------------ + + First, you ... + + + Extract the mesh + ---------------- + + Then, you extract ... + + + Plot the mesh + ------------- + + Finally, you plot ... + +Tabs +~~~~ + +You must use tabs when a step requires a solver-specific implementation. + +These tabs looks like: + +.. tab-set:: + + .. tab-item:: MAPDL + + Explanation 1 ... + + .. jupyter-execute:: + + # Code block 1 + + .. tab-item:: LSDYNA + + Explanation 2 ... + + .. jupyter-execute:: + + # Code block 2 + + .. tab-item:: Fluent + + Explanation 3 ... + + .. jupyter-execute:: + + # Code block 3 + + .. tab-item:: CFX + + Explanation 4 ... + + .. jupyter-execute:: + + # Code block 4 + + +You can also use tabs if you want to show different approaches to one step and it having the code blocks +in different tabs is clearer. You can see an example of this in the +:ref:`ref_tutorials_animate_time` tutorial. + + +Code blocks +~~~~~~~~~~~ + +The tutorials must have code blocks where you show how you actually implement the code. +In addition to the guidelines presented here, you must also follow the `Coding style `_ +guide to ensure that all code looks the same across the project. + +- Use the `jupyter sphinx `_ extension to show code blocks. It executes embedded code in + a Jupyter kernel and embeds outputs of that code in the document: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + .. jupyter-execute:: + + # This is a executable code block + from ansys.dpf import core as dpf + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + .. code-block:: + + # This is a simple code block + from ansys.dpf import core as dpf + +- Use comments within a code block to clarify the purpose of a line: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + # Define the model + model = dpf.Model() + + # Get the stress results + stress_fc = model.results.stress.eval() + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + model = dpf.Model() + stress_fc = model.results.stress.eval() + +- Split your code in several parts to include longer explanations in text format or force showing an intermediate code output: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + Explanation for a first code block and its output + + .. code-block:: + + # Code comment 1 + code1 + + Explanation for a second code block and its output + + .. code-block:: + + # Code comment 2 + code2 + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + A single broad explanation for two steps with outputs mixed together + + .. code-block:: + + # First explanation + # Code comment 1 + code1 + + # Second explanation + # Code comment 2 + code2 + +- When using a PyDPF-Core object or method you must name arguments: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + # Get the stress results + stress_fc = model.results.stress(time_scoping=time_steps).eval() + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + # Get the stress results + stress_fc = model.results.stress(time_steps).eval() + +- When quoting APIs in the code comments you must always use their scripting name. Mind the use of + a capital letter to name the DPF objects + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + # Define the DataSources object + ds = dpf.DataSources() + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + # Define the data sources object + ds = dpf.DataSources() + + .. code-block:: + + # Define the Data Sources object + ds = dpf.DataSources() + +- Use blank lines between code lines for better clarity. + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + # Define the result file path + result_file_path_1 = '/tmp/file.rst' + + # Define the DataSources object + ds_1 = dpf.DataSources(result_path=result_file_path_1) + + # Create a Model + model_1 = dpf.Model(data_sources=ds_1) + + # Get the stress results + stress_fc = model_1.results.stress.eval() + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + # Define the result file path + result_file_path_1 = '/tmp/file.rst' + # Define the DataSources object + ds_1 = dpf.DataSources(result_path=result_file_path_1) + # Create a Model + model_1 = dpf.Model(data_sources=ds_1) + # Get the stress results + stress_fc = model_1.results.stress.eval() + +- Avoid naming the variables with the same name as an argument or an API. You can get inspirations from the + tutorials available at :ref:`ref_tutorials`. + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + # Define the result file path + result_file_path = '/tmp/file.rst' + + # Define the DataSources object + ds = dpf.DataSources(result_path=result_file_path) + + # Create a Model + my_model = dpf.Model(data_sources=ds) + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + # Define the result file path + result_path = '/tmp/file.rst' + + # Define the DataSources object + data_sources = dpf.DataSources(result_path=result_path) + + # Create a Model + model = dpf.Model(data_sources=data_sources) + +Text formating +~~~~~~~~~~~~~~ + +In addition to the guidelines presented here, you must also follow the `Documentation style `_ +guide to ensure that the tutorials follow a coherent writing style across the project. + +- When quoting APIs in the text you must always use a reference to redirect it to the API reference + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + Here we use the |MeshedRegion| substitution text + + **Rendered text:** + + Here is some text. Here we use the |MeshedRegion| substitution text + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + Here we do not use the MeshedRegion substitution text + + **Rendered text:** + + Here is some text. Here we do not use the MeshedRegion substitution text + +- Use bullet lists when enumerating items: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + This operator accepts as arguments: + + - A Result + - An Operator + - A FieldsContainer + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + This operator accepts a Result, an Operator or a + FieldsContainer as arguments. + +- Use a numbered list for ordered items: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + To extract the mesh you need to follow those steps: + + #. Get the result file; + #. Create a Model; + #. Get the MeshedRegion. + + The ``#.`` renders as a numbered list. + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + To extract the mesh you need to follow those steps: + + - Get the result file; + - Create a Model; + - Get the MeshedRegion. + +- If you need to develop explanations for each item of the list, first, enumerate and reference them. Then, + explore each of them separately in sub headings. + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + Section title + ------------- + + This section presents two items: + + - :ref:`Item 1 ` + - :ref:`Content` + + + .. _ref_tutorial_name_item_1: + + Item 1 + ^^^^^^ + + Presentation of the first item... + + + .. _ref_tutorial_name_item_2: + + Item 2 + ^^^^^^ + + Presentation of the second item... + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + Section title + ------------- + + This section presents two items: + + - Item 1 + - Item 2 + + Item 1 + ^^^^^^ + Presentation of the first item... + + Item 2 + ^^^^^^ + Presentation of the second item... + + + .. code-block:: + + Section title + ------------- + + This section presents two items: + + - Item 1 + Presentation of the first item... + + + - Item 2 + Presentation of the second item... diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst new file mode 100644 index 0000000000..500a506212 --- /dev/null +++ b/doc/source/getting_started/write_doc/index.rst @@ -0,0 +1,136 @@ +.. _ref_write_doc: + +============= +Documentation +============= + +Overall guidance on contributing to the documentation of a PyAnsys repository appears in +`Documenting `_ in the *PyAnsys Developer's Guide*. + +You must also follow the `Documentation style `_ guide to +ensure that all the documentation looks the same across the project. + +To improve the documentation you need to: + +- Start by `cloning the repository `_; +- Follow the `guidelines `_ to the corresponding documentation part you want to develop; +- Check the new documentation by `viewing the documentaion `_ + +Clone the repository +-------------------- + +Clone and install the latest version of PyDPF-Core in +development mode by running this code: + +.. code:: + + git clone https://github.com/ansys/pydpf-core + cd pydpf-core + pip install -e . + + +Guidelines +---------- + +Our documentation tries to follow a structure principle that respects four different functions of the documentation. +Each of them fulfills a different need for people working with our tool at different times, in different circumstances. + +Here is an overview of how our documentation is organized to help you know where you should include your contributions. +Each section has their own guidelines that must be followed when creating new content. + +.. grid:: 1 1 2 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: **TUTORIALS** + :link: ref_guidelines_tutorials + :link-type: ref + :class-title: sd-text-center sd-bg-light + :class-header: sd-text-center + + Learning oriented + ^^^^^^^^^^^^^^^^^ + + **Function:** Teach how to get started and use PYDPF-core step by step + + They are designed to teach how to perform a task and understand the underlying concepts, + providing detailed explanations at each stage. The task is built around the application of specific features. + + +++ + .. rubric:: Guidelines + + Here you find guidelines and templates to write new tutorials. + + .. grid-item-card:: **EXAMPLES** + :link: ref + :link-type: ref + :class-title: sd-text-center sd-bg-light + :class-header: sd-text-center + + Use-cases oriented + ^^^^^^^^^^^^^^^^^^ + + **Function:** Show how to solve specifics key problems + + They showcase specific key problems and use-cases. They are more advanced than + tutorials as they present end-to-end engineering workflows and assume basic knowledge of PyDPF-Core. + + +++ + .. rubric:: Guidelines + + Here you find guidelines and templates to write new examples. + + .. grid-item-card:: **CONCEPTS** + :link: ref + :link-type: ref + :class-title: sd-text-center sd-bg-light + :class-header: sd-text-center + + Understanding oriented + ^^^^^^^^^^^^^^^^^^^^^^ + + **Function:** Provide useful theoretical explanations for PyDPF-Core + + They discuss and explain key DPF principles and concepts, enabling the reader to understand the spirit of the underlying tool. + + +++ + .. rubric:: Guidelines + + Here you find guidelines and templates to write more concepts. + + + .. grid-item-card:: **API REFERENCE** + :link: ref + :link-type: ref + :class-title: sd-text-center sd-bg-light + :class-header: sd-text-center + + Informing oriented + ^^^^^^^^^^^^^^^^^^ + + **Function:** Describe PyDPF-Core APIs + + They contain technical reference on how PyDPF-Core works and how to use it but assume basic + understanding of key DPF concepts. It is generated automatically along the documentation and + is based on the source code. + + +++ + .. rubric:: Guidelines + + Here you find guidelines and templates to improve the API reference. + +View the documentation +---------------------- + +Documentation for the latest stable release of PyDPF-Core is hosted at +`PyDPF-Core Documentation `_. + +You can locally build the documentation by following the steps in +`Contributing `_ in the *PyAnsys Developer's Guide*. + +.. toctree:: + :maxdepth: 2 + :hidden: + + guidelines_tutorials.rst diff --git a/doc/source/getting_started/write_doc/tutorial_card_template.rst b/doc/source/getting_started/write_doc/tutorial_card_template.rst new file mode 100644 index 0000000000..646a9e98c8 --- /dev/null +++ b/doc/source/getting_started/write_doc/tutorial_card_template.rst @@ -0,0 +1,9 @@ +.. grid-item-card:: Tutorial title + :link: ref + :link-type: ref + :text-align: center + + This tutorial ... + + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` \ No newline at end of file diff --git a/doc/source/getting_started/write_doc/tutorial_content_template.rst b/doc/source/getting_started/write_doc/tutorial_content_template.rst new file mode 100644 index 0000000000..a9ab884794 --- /dev/null +++ b/doc/source/getting_started/write_doc/tutorial_content_template.rst @@ -0,0 +1,96 @@ + +Tabs for different solvers +-------------------------- + +Showcase a different script for each supported solvers + +.. tab-set:: + + .. tab-item:: MAPDL + + Explanation ... + + .. jupyter-execute:: + + # Code block + + .. tab-item:: LSDYNA + + Explanation ... + + .. jupyter-execute:: + + # Code block + + .. tab-item:: Fluent + + Explanation ... + + .. jupyter-execute:: + + # Code block + + .. tab-item:: CFX + + Explanation ... + + .. jupyter-execute:: + + # Code block + +Bullet lists +------------ + +Enumerate something: + +- something 1; +- something 2; +- something 3. + +Enumerate something with a numbered list: + +#. something 1; +#. something 2; +#. something 3. + +Bullet lists with explanations between items +-------------------------------------------- + +Enumerate something and reference them to use each item as a subheading: + +- :ref:`Something 1`; +- :ref:`Something 2`; +- :ref:`Something 3`. + +.. _ref_something_1: + +Something 1 +^^^^^^^^^^^ + +Explanation 1 + +.. jupyter-execute:: + + # Code block 1 + +.. _ref_something_2: + +Something 2 +^^^^^^^^^^^ + +Explanation 2 + +.. jupyter-execute:: + + # Code block 2 + +.. _ref_something_3: + +Something 3 +^^^^^^^^^^^ + +Explanation 3 + +.. jupyter-execute:: + + # Code block 3 diff --git a/doc/source/getting_started/write_doc/tutorial_section_template.rst b/doc/source/getting_started/write_doc/tutorial_section_template.rst new file mode 100644 index 0000000000..16ea42a6a3 --- /dev/null +++ b/doc/source/getting_started/write_doc/tutorial_section_template.rst @@ -0,0 +1,28 @@ +.. _ref_tutorial_new_section_template: + +============= +Section title +============= + +These tutorials demonstrate how to ... + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Tutorial title + :link: ref + :link-type: ref + :text-align: center + + This tutorial ... + + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` + +.. toctree:: + :maxdepth: 2 + :hidden: + + tutorial_file.rst \ No newline at end of file diff --git a/doc/source/getting_started/write_doc/tutorial_structure_template.rst b/doc/source/getting_started/write_doc/tutorial_structure_template.rst new file mode 100644 index 0000000000..8b7536c1cb --- /dev/null +++ b/doc/source/getting_started/write_doc/tutorial_structure_template.rst @@ -0,0 +1,41 @@ +.. _ref_tutorial_template: + +============== +Tutorial title +============== + +.. |displacement_op| replace:: :class:`ansys.dpf.core.operators.result.displacement.displacement` + +A single sentence describing the goal of the tutorial, which must match the one on the tutorial card in the section page. + +Introduction to the tutorial. Here, you provide the necessary context or foundational information for understanding the tutorial. + +:jupyter-download-script:`Download tutorial as Python script` +:jupyter-download-notebook:`Download tutorial as Jupyter notebook` + +First Step +---------- + +First, you ... + +.. jupyter-execute:: + + # Code block 1 + +Second step +----------- + +Then, you ... + +.. jupyter-execute:: + + # Code block 2 + +Final Step +---------- + +Finally, you ... + +.. jupyter-execute:: + + # Code block 3 diff --git a/doc/source/links_and_refs.rst b/doc/source/links_and_refs.rst index 1bb88ec64a..f6590b5549 100644 --- a/doc/source/links_and_refs.rst +++ b/doc/source/links_and_refs.rst @@ -2,6 +2,12 @@ .. LINKS +.. PyDPF-Core +.. _pydpfcore_issues: https://github.com/ansys/pydpf-core/issues +.. _pydpfcore_discussions: https://github.com/ansys/pydpf-core/discussions +.. _pydpfcore_latest_release: https://github.com/ansys/pydpf-core/releases/latest +.. _pydpfcore_documentation: https://dpf.docs.pyansys.com/ + .. Pyansys .. _pyansys: https://docs.pyansys.com/version/dev/ @@ -12,13 +18,17 @@ .. _dev_guide_setup_your_environment: https://dev.docs.pyansys.com/how-to/setting-up.html .. _dev_guide_branch_names: https://dev.docs.pyansys.com/how-to/contributing.html#branch-naming-conventions .. _dev_guide_commit_names: https://dev.docs.pyansys.com/how-to/contributing.html#commit-naming-conventions +.. _dev_guide_doc_style: https://dev.docs.pyansys.com/doc-style/index.html +.. _dev_guide_documenting: https://dev.docs.pyansys.com/how-to/documenting.html# .. Other libraries documentations .. _pyvista_docs: https://docs.pyvista.org/version/stable/ .. _pyvista_doc_plot_method: https://docs.pyvista.org/api/plotting/_autosummary/pyvista.plot.html#pyvista.plot +.. _pyvista_org: https://pyvista.org/ .. _jupyter: https://jupyter.org/ .. _numpy_org: https://numpy.org/ .. _numpy_docs: https://numpy.org/doc/stable/ +.. _jupyter_sphinx_ext: https://jupyter-sphinx.readthedocs.io/en/latest/ .. Other libraries repos .. _pyvista_github : https://github.com/pyvista/pyvista @@ -26,9 +36,13 @@ .. External links .. _sphinx: https://www.sphinx-doc.org/en/master/ .. _sphinx_directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html +.. _sphinx_basics: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _vale: https://www.vale.sh .. _docutils_directives: https://docutils.sourceforge.io/docs/ref/rst/directives.html .. _numpy_sphinx_ext_doc: https://numpydoc.readthedocs.io/en/latest/ +.. _pip_pypi_page: https://pypi.org/project/pip/ +.. _pyvista_download_files: https://pypi.org/project/pyvista/#files +.. _matplotlib_download_files: https://pypi.org/project/matplotlib/#files .. REFERENCES