Skip to content

Commit 0a8fa75

Browse files
luisaFelixSallesPProfizi
luisaFelixSalles
and
PProfizi
authored
Add tutorials guidelines in the main tutorials branch (#1950)
* add new basic tutorial and jupyter_ sphinx extension * separate the documentation part from the contributing.rst (main page) * create the index page for the writing documentation section * add the tutorials guide lines file * add the tutorial template file * updates the contributing.rst main page * add a separate section for develop code (contributing) * add the writing documentation index page * add new links to links_and_refs.rst * add tutorial_card_template.rst * add tutorial_section_template.rst * add toctree to index file of the write_doc folder * add first part of the guide_lines_tutorials.rst * updates * final first version of guide_lines_tutorials.rst * add tutorial_content_template.rst * add tutorial_structure_template.rst * updates the guide_lines_tutorials.rst with the new tutorial templates refs * updates the guide_lines_tutorials.rst * delete file basic_tutorial.rst * Update doc/source/getting_started/write_doc/guide_lines_tutorials.rst * Update doc/source/getting_started/write_doc/tutorial_structure_template.rst * Apply suggestions from code review Co-authored-by: Paul Profizi <[email protected]> * updates the links references in the rst files * updates the links references in the install.rst file * redirect to the PyAnsys guidelines for developing code and add the installation explanation before cloning * redirect to the PyAnsys guidelines for developing documentation * add new links and substitution text to the links_and_refs.rst file * update text in index.rst (write doc) * update the guide_lines_tutorials.rst * update the tutorial_structure_template.rst * add the installing dpf server explanation to the write code index.rst * add the link to the jupyter execute extension doc to the links_and_refs.rst file * rename the guidelines_tutorials.rst file * updates the guidelines_tutorials.rst name in the toctree of the write doc index.rst * Apply suggestions from code review Co-authored-by: Paul Profizi <[email protected]> * Apply suggestions from code review Co-authored-by: Paul Profizi <[email protected]> * Apply suggestions from code review Co-authored-by: Paul Profizi <[email protected]> * Update doc/source/getting_started/write_doc/guidelines_tutorials.rst Co-authored-by: Paul Profizi <[email protected]> * Apply suggestions from code review Co-authored-by: Paul Profizi <[email protected]> * updates the index.rst of the write doc section * add a new link to the links_and_refs.rst file --------- Co-authored-by: Paul Profizi <[email protected]>
1 parent 293a63d commit 0a8fa75

File tree

10 files changed

+1158
-28
lines changed

10 files changed

+1158
-28
lines changed

‎doc/source/getting_started/contributing.rst‎

Lines changed: 75 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,38 +4,90 @@
44
Contributing
55
============
66

7+
There are several ways to contribute to PyDPF-Core:
8+
9+
- :ref:`ref_contributing_answer_discussions`
10+
- :ref:`ref_contributing_post_issues`
11+
- :ref:`ref_contributing_develop_code`
12+
- :ref:`ref_contributing_improve_doc`
13+
714
Overall guidance on contributing to a PyAnsys repository appears in
8-
`Contribute <https://dev.docs.pyansys.com/overview/contributing.html>`_
9-
in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar
10-
with this guide before attempting to contribute to PyDPF-Core.
11-
15+
`Contributing <dev_guide_contributing_>`_ in the *PyAnsys Developer's Guide*.
16+
Ensure that you are thoroughly familiar with this guide before attempting
17+
to contribute to PyDPF-Core.
18+
1219
The following contribution information is specific to PyDPF-Core.
1320

14-
Clone the repository
15-
--------------------
16-
Clone and install the latest version of PyDPF-Core in
17-
development mode by running this code:
21+
.. _ref_contributing_answer_discussions:
1822

19-
.. code::
23+
Answer discussions
24+
------------------
25+
26+
Answering discussions is an excellent way to contribute to PyDPF-Core, and it does not require
27+
any setup, just a GitHub account. Engaging in discussions often requires a thorough grasp of
28+
the project’s goals and challenges. Your contributions can help other users or contributors who may be
29+
facing similar issues, making the repository more welcoming and inclusive. By providing answers or solutions,
30+
you can directly contribute to the project’s success, maintain its health, and encourage a positive,
31+
open source ecosystem.
2032

21-
git clone https://github.com/ansys/pydpf-core
22-
cd pydpf-core
23-
pip install -e .
33+
To discover how you can help see the `PyDPF-Core Discussions page <pydpfcore_discussions_>`_.
2434

35+
.. _ref_contributing_post_issues:
2536

2637
Post issues
2738
-----------
28-
Use the `PyDPF-Core Issues <https://github.com/ansys/pydpf-core/issues>`_
29-
page to submit questions, report bugs, and request new features.
3039

31-
To reach the project support team, email `[email protected] <[email protected]>`_.
40+
Posting issues in a repository allows you to voice concerns, suggest improvements, or report bugs, which can
41+
lead to a more robust and user-friendly project. It also offers an opportunity for you to engage with the
42+
project’s community, learn from others, and gain experience in issue tracking and collaboration.
43+
44+
For the repository, issues serve as a structured way to track and prioritize work, helping maintainers understand
45+
the needs of users and guide the project’s development.
46+
47+
Use the `PyDPF-Core Issues page <pydpfcore_issues_>`_ to submit questions, report bugs, and request new features. When possible, use
48+
these issue templates:
49+
50+
- 🐞 Bug, problem, or error: Fill a bug report here;
51+
- 📖 Documentation issue: Modifications to the documentation only;
52+
- 🎓 Adding an example: Proposing a new example for the library;
53+
- 🎓 Adding an tutorial: Proposing a new tutorial for the library;
54+
- 💡 New feature: Enhancements to the code;
55+
- If your issue does not fit into one of these categories create a blank issue.
56+
57+
To reach the project support team, email `[email protected] <[email protected]>`_
58+
59+
.. _ref_contributing_develop_code:
60+
61+
Develop code
62+
------------
63+
64+
You can help improve PyDPF-Core by fixing a bug. To do it, you must set up the repository on your local
65+
machine as per the explanations in the :ref:`ref_write_code` section.
66+
67+
68+
.. _ref_contributing_improve_doc:
69+
70+
Improve documentation
71+
---------------------
72+
73+
The PyDPF-Core documentation plays a pivotal role in making the project more accessible and usable.
74+
Clear and comprehensive documentation empowers users and developers to understand, implement, and
75+
troubleshoot the project effectively. It minimizes barriers to entry, making it easier for newcomers
76+
to get involved and for existing contributors to be more productive.
77+
78+
Good documentation also reduces the burden on maintainers, as it can answer common questions and
79+
help prevent issues. By creating or improving documentation, you not only enhance the project’s quality but
80+
also facilitate knowledge sharing and community growth, making your contribution invaluable for the project’s
81+
long-term success.
82+
83+
To contribute on our current documentation go to the :ref:`ref_write_doc` section.
84+
85+
.. toctree::
86+
:maxdepth: 2
87+
:hidden:
88+
89+
write_doc/index.rst
90+
write_code/index.rst
91+
3292

33-
View documentation
34-
------------------
35-
Documentation for the latest stable release of PyDPF-Core is hosted at
36-
`PyDPF-Core Documentation <https://dpf.docs.pyansys.com/>`_.
3793

38-
In the upper right corner of the documentation's title bar, there is an option
39-
for switching from viewing the documentation for the latest stable release
40-
to viewing the documentation for the development version or previously
41-
released versions.

‎doc/source/getting_started/install.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Installation
77
Install using ``pip``
88
---------------------
99

10-
The standard package installer for Python is `pip <https://pypi.org/project/pip/>`_.
10+
The standard package installer for Python is `pip <pip_pypi_page_>`_.
1111

1212
To use PyDPF-Core with Ansys 2022 R2 or later, install the latest version
1313
with this command:
@@ -16,7 +16,7 @@ with this command:
1616
1717
pip install ansys-dpf-core
1818
19-
PyDPF-Core plotting capabilities require to have `PyVista <https://pyvista.org/>`_ installed.
19+
PyDPF-Core plotting capabilities require to have `PyVista <pyvista_org_>`_ installed.
2020
To install PyDPF-Core with its optional plotting functionalities, use:
2121

2222
.. code::
@@ -52,7 +52,7 @@ Install without internet
5252

5353
If you are unable to install PyDPF-Core on the host machine using ``pip`` due to
5454
network isolation, download the wheelhouse corresponding to your platform and Python interpreter version
55-
for the latest release of PyDPF-Core from the assets section of the `latest PyDPF-Core release on GitHub <https://github.com/ansys/pydpf-core/releases/latest>`_.
55+
for the latest release of PyDPF-Core from the assets section of the `latest PyDPF-Core release on GitHub <pydpfcore_latest_release>`_.
5656

5757
The wheelhouse is a ZIP file containing Python wheels for all the packages PyDPF-Core requires to run.
5858
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:
6464
6565
Beware that PyDPF-Core wheelhouses do not include the optional plotting dependencies.
6666
To allow for plotting capabilities, also download the wheels corresponding to your platform and Python interpreter version
67-
for `PyVista <https://pypi.org/project/pyvista/#files>`_ and
68-
`matplotlib <https://pypi.org/project/matplotlib/#files>`_, then place them in the same previous local directory and run the command above.
67+
for `PyVista <pyvista_download_files_>`_ and
68+
`matplotlib <matplotlib_download_files_>`_, then place them in the same previous local directory and run the command above.
6969

7070

7171
Install in development mode

‎doc/source/getting_started/write_code/index.rst‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
.. _ref_write_code:
2+
3+
============
4+
Develop code
5+
============
6+
7+
You can help improve PyDPF-Core by fixing a bug. To do it, you must set up the repository
8+
on your local machine as per the following steps:
9+
10+
- :ref:`ref_write_code_install`
11+
- :ref:`ref_write_code_clone`
12+
- :ref:`ref_write_code_check_install`
13+
- :ref:`ref_write_code_develop_code`
14+
15+
.. _ref_write_code_install:
16+
17+
Install the repository and the DPF server
18+
-----------------------------------------
19+
20+
Install the PyDPF-Core repository by following the steps in :ref:`installation` and :ref:`ref_dpf_server`.
21+
22+
.. _ref_write_code_clone:
23+
24+
Clone the repository
25+
--------------------
26+
27+
Before cloning the PyDPF-Core repository, you must install a version control system such as Git.
28+
29+
Then, clone the latest version of PyDPF-Core in development mode (using ``pip`` with the ``-e``
30+
development flag) by running this code:
31+
32+
.. code::
33+
34+
git clone https://github.com/ansys/pydpf-core
35+
cd pydpf-core
36+
pip install -e .
37+
38+
.. _ref_write_code_check_install:
39+
40+
Check the installation
41+
----------------------
42+
43+
Run the following Python code to verify your PyDPF-Core installation:
44+
45+
.. code::
46+
47+
from ansys.dpf.core import Model
48+
from ansys.dpf.core import examples
49+
model = Model(examples.find_simple_bar())
50+
print(model)
51+
52+
.. _ref_write_code_develop_code:
53+
54+
Develop the PyDPF-Core code
55+
---------------------------
56+
57+
Overall guidance on contributing to the code of a PyAnsys repository appears in
58+
`Contributing <dev_guide_contributing_>`_ in the *PyAnsys Developer's Guide*.
59+
60+
You must also follow the `Coding style <dev_guide_coding_style_>`_ guide to ensure
61+
that all source code looks the same across the project.

0 commit comments

Comments
 (0)