Skip to content

Commit fba63d4

Browse files
Revathyvenugopal162Revathyvenugopal162
committed
docs: add contribute session
1 parent 51700b5 commit fba63d4

File tree

9 files changed

+358
-3
lines changed

9 files changed

+358
-3
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ share/python-wheels/
2828
.installed.cfg
2929
*.egg
3030
MANIFEST
31+
.DS_Store
3132

3233
# PyInstaller
3334
# Usually these files are written by a python script from a template

‎doc/changelog.d/636.documentation.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs: add contribute session

‎doc/source/conf.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
from datetime import datetime
44
import os
55
from pathlib import Path
6+
import subprocess
67
from typing import List
78

89
from github import Github
@@ -162,6 +163,11 @@
162163
"version": f"v{version}" if not version.endswith("dev0") else "main",
163164
},
164165
"pdf_guide": {"version": get_version_match(__version__)}, # noqa: E501
166+
"toxenvs": {
167+
"envs": subprocess.run(
168+
["tox", "list", "-d", "-q"], capture_output=True, text=True
169+
).stdout.splitlines()[1:],
170+
},
165171
}
166172

167173

@@ -297,3 +303,8 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
297303

298304
jinja_contexts["examples"] = {"inputs_examples": file_names}
299305
jinja_contexts["admonitions"] = {"inputs_admonitions": admonitions_links}
306+
307+
308+
jinja_globals = {
309+
"ANSYS_SPHINX_THEME_VERSION": version,
310+
}

‎doc/source/contribute.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
2+
Contribute
3+
##########
4+
5+
Thank you for your interest in contributing to Ansys Sphinx theme! Contributions are welcome
6+
to make the project better, whether it's fixing bugs, adding new features, or
7+
improving documentation. Below are the guidelines to follow when contributing.
8+
9+
.. toctree::
10+
:hidden:
11+
:maxdepth: 1
12+
:caption: Contribute
13+
14+
User<contribute/user>
15+
Developer<contribute/developer>

‎doc/source/contribute/developer.rst‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
Contributing as a developer
2+
###########################
3+
4+
.. grid:: 1 1 3 3
5+
6+
.. grid-item-card:: :fa:`code-fork` Fork the repository
7+
:padding: 2 2 2 2
8+
:link: fork-the-repository
9+
:link-type: ref
10+
11+
Learn how to fork the project and get your own copy.
12+
13+
.. grid-item-card:: :fa:`download` Clone the repository
14+
:padding: 2 2 2 2
15+
:link: clone-the-repository
16+
:link-type: ref
17+
18+
Download your own copy in your local machine.
19+
20+
.. grid-item-card:: :fa:`download` Install for developers
21+
:padding: 2 2 2 2
22+
:link: install-for-developers
23+
:link-type: ref
24+
25+
Install the project in editable mode.
26+
27+
28+
.. _fork-the-repository:
29+
30+
Fork the repository
31+
===================
32+
33+
Forking the repository is the first step to contributing to the project. This
34+
allows you to have your own copy of the project so you can make changes without
35+
affection the main project. Once you have made your changes, you can submit a
36+
pull-request to the main project to have your changes reviewed and merged.
37+
38+
.. button-link:: https://github.com/ansys/ansys-sphinx-theme/fork
39+
:color: primary
40+
:align: center
41+
42+
:fa:`code-fork` Fork this project
43+
44+
.. note::
45+
46+
If you are an Ansys employee, you can skip this step.
47+
48+
.. _clone-the-repository:
49+
50+
Clone the repository
51+
====================
52+
53+
Make sure you `configure SSH`_ with your GitHub
54+
account. This allows you to clone the repository without having to use tokens
55+
or passwords. Also, make sure you have `git`_ installed in your machine.
56+
57+
To clone the repository using SSH, run:
58+
59+
.. code-block:: bash
60+
61+
git clone [email protected]:ansys/ansys-sphinx-theme
62+
63+
.. _install-for-developers:
64+
65+
Install for developers
66+
======================
67+
68+
Installing Ansys sphinx theme in development mode allows you to perform changes to the code
69+
and see the changes reflected in your environment without having to reinstall
70+
the library every time you make a change.
71+
72+
Virtual environment
73+
-------------------
74+
75+
Start by navigating to the project's root directory by running:
76+
77+
.. code-block::
78+
79+
cd ansys-sphinx-theme
80+
81+
Then, create a new virtual environment named ``.venv`` to isolate your system's
82+
Python environment by running:
83+
84+
.. code-block:: text
85+
86+
python -m venv .venv
87+
88+
Finally, activate this environment by running:
89+
90+
.. tab-set::
91+
92+
.. tab-item:: Windows
93+
94+
.. tab-set::
95+
96+
.. tab-item:: CMD
97+
98+
.. code-block:: text
99+
100+
.venv\Scripts\activate.bat
101+
102+
.. tab-item:: PowerShell
103+
104+
.. code-block:: text
105+
106+
.venv\Scripts\Activate.ps1
107+
108+
.. tab-item:: macOS/Linux/UNIX
109+
110+
.. code-block:: text
111+
112+
source .venv/bin/activate
113+
114+
Development mode
115+
----------------
116+
117+
Now, install Ansys sphinx theme in editable mode by running:
118+
119+
.. code-block:: text
120+
121+
python -m pip install --editable .
122+
123+
Verify the installation by checking the version of the library:
124+
125+
126+
.. code-block:: python
127+
128+
from ansys_sphinx_theme import __version__
129+
130+
131+
print(f"Ansys sphinx thenme version is {__version__}")
132+
133+
.. jinja::
134+
135+
.. code-block:: text
136+
137+
>>> Ansys sphinx theme version is {{ ANSYS_SPHINX_THEME_VERSION }}
138+
139+
Install Tox
140+
-----------
141+
142+
Once the project is installed, you can install `Tox`_. This is a cross-platform
143+
automation tool. The main advantage of Tox is that it allows you to test your
144+
project in different environments and configurations in a temporary and
145+
isolated Python virtual environment. To install Tox, run:
146+
147+
.. code-block:: text
148+
149+
python -m pip install tox
150+
151+
Finally, verify the installation by listing all the different environments
152+
(automation rules) for Ansys Sphinx theme:
153+
154+
.. code-block:: text
155+
156+
python -m tox list
157+
158+
.. jinja:: toxenvs
159+
160+
.. dropdown:: Default Tox environments
161+
:animate: fade-in
162+
:icon: three-bars
163+
164+
.. list-table::
165+
:header-rows: 1
166+
:widths: auto
167+
168+
* - Environment
169+
- Description
170+
{% for environment in envs %}
171+
{% set name, description = environment.split("->") %}
172+
* - {{ name }}
173+
- {{ description }}
174+
{% endfor %}
175+
176+
177+
Adhere to code style
178+
--------------------
179+
180+
Ansys Sphinx theme follows the PEP8 standard as outlined in
181+
`PEP 8 <https://dev.docs.pyansys.com/coding-style/pep8.html>`_ in
182+
the *PyAnsys Developer's Guide* and implements style checking using
183+
`pre-commit <https://pre-commit.com/>`_.
184+
185+
To ensure your code meets minimum code styling standards, run these commands::
186+
187+
pip install pre-commit
188+
pre-commit run --all-files
189+
190+
or use tox as above::
191+
192+
tox -e code-style
193+
194+
You can also install this as a pre-commit hook by running this command::
195+
196+
pre-commit install
197+
198+
This way, it's not possible for you to push code that fails the style checks::
199+
200+
$ pre-commit install
201+
$ git commit -am "added my cool feature"
202+
ruff.....................................................................Passed
203+
ruff-format..............................................................Passed
204+
codespell................................................................Passed
205+
prettier.................................................................Passed
206+
check for merge conflicts................................................Passed
207+
debug statements (python)................................................Passed
208+
check yaml...............................................................Passed
209+
trim trailing whitespace.................................................Passed
210+
Validate GitHub Workflows................................................Passed
211+
Add License Headers......................................................Passed

‎doc/source/contribute/user.rst‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
Contributing as a user
2+
######################
3+
4+
Users can contribute in a variety of ways, such as reporting bugs, requesting
5+
new features, testing in-development features, starting discussions, answering
6+
questions, and sharing their work with the community.
7+
8+
.. warning::
9+
10+
Do not include any proprietary or sensitive information when reporting bugs
11+
or showcasing your work.
12+
13+
.. grid:: 1 1 3 3
14+
15+
.. grid-item-card:: :fa:`bug` Report bugs
16+
:padding: 2 2 2 2
17+
:link: report-bugs
18+
:link-type: ref
19+
20+
Found a bug? Report it here.
21+
22+
.. grid-item-card:: :fa:`lightbulb` Request a new feature
23+
:padding: 2 2 2 2
24+
:link: request-a-new-feature
25+
:link-type: ref
26+
27+
Got an idea for a new feature? Share it!
28+
29+
.. grid-item-card:: :fa:`vial-circle-check` Test a new feature
30+
:padding: 2 2 2 2
31+
:link: test-a-new-feature
32+
:link-type: ref
33+
34+
Anxious to try out a new feature? Here's how you can do it.
35+
36+
.. grid-item-card:: :fa:`comment-dots` Answer questions
37+
:padding: 2 2 2 2
38+
:link: answer-questions
39+
:link-type: ref
40+
41+
Help others by answering their questions.
42+
43+
.. grid-item-card:: :fa:`bullhorn` Share your work
44+
:padding: 2 2 2 2
45+
:link: share-your-work
46+
:link-type: ref
47+
48+
Share your work with the community.
49+
50+
.. _report-bugs:
51+
52+
Report bugs
53+
===========
54+
55+
If you encounter a bug or an issue while using the project, please report it.
56+
Your feedback helps to identify problems.
57+
58+
- Search the `Ansys sphinx theme issue`_ to see if the issue has already been reported.
59+
60+
- Create a new issue if it hasn’t been reported.
61+
62+
- Include a clear description of the problem.
63+
- Provide steps to reproduce the issue.
64+
- Mention the version of the project you're using.
65+
- Include screenshots or logs if possible.
66+
67+
.. _request-a-new-feature:
68+
69+
Request a new feature
70+
=====================
71+
72+
Do you have an idea for a new feature or an improvement? Your suggestions are
73+
welcome. You can request a new feature by creating an issue in the `Ansys sphinx theme issue`_
74+
board.
75+
76+
.. _test-a-new-feature:
77+
78+
Test a new feature
79+
==================
80+
81+
It is possible to test a new feature before it is officially released. To do
82+
so, you can install Ansys Sphinx theme from the source code.
83+
84+
.. _answer-questions:
85+
86+
Answer questions
87+
================
88+
89+
Another great way to contribute is to help others by answering their questions.
90+
Maintain a positive and constructive attitude while answering questions. If you
91+
don't know the answer, you can still help by pointing the person in the right
92+
direction.
93+
94+
.. _share-your-work:
95+
96+
Share your work
97+
===============
98+
99+
If you have used Ansys Sphinx theme to create something interesting, share it with the rest
100+
of the community. You can share your work in the `Ansys sphinx theme issue`_. Include
101+
a brief description of your work and any relevant links that others may find
102+
useful.

‎doc/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,3 +54,4 @@ are included in the theme to make documentation more appealing and user-friendly
5454
examples.rst
5555
{% endif %}
5656
changelog
57+
contribute.rst

0 commit comments

Comments
 (0)