Skip to content

Commit c788fc1

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

File tree

8 files changed

+320
-3
lines changed

8 files changed

+320
-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/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: 3
12+
:caption: Contribute
13+
14+
User<contribute/user>
15+
Developer<contribute/developer>

‎doc/source/contribute/developer.rst‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
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 PySTK:
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 %}

‎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 issues`_. 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

‎doc/source/links.rst‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
.. _PyData_PyPI: https://pypi.org/project/pydata-sphinx-theme/
1313
.. _Jinja2_PyPI: https://pypi.org/project/Jinja2/
1414
.. _pip: https://pypi.org/project/pip/
15+
.. _Tox: https://tox.wiki/en/stable/
1516

1617
.. dependency docs links
1718
.. _sphinx_design_examples: https://github.com/executablebooks/sphinx-design/tree/furo-theme/docs/snippets/rst
@@ -22,4 +23,10 @@
2223

2324
.. ansys_sphinx_theme links
2425
25-
.. _static_files: https://github.com/ansys/ansys-sphinx-theme/blob/main/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/logos/
26+
.. _static_files: https://github.com/ansys/ansys-sphinx-theme/blob/main/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/logos/
27+
.. _Ansys sphinx theme issue: https://github.com/ansys/ansys-sphinx-theme/issues/
28+
29+
30+
.. other links
31+
.. _git: https://git-scm.com/
32+
.. _configure SSH: https://docs.github.com/en/authentication/connecting-to-github-with-ssh

‎tox.ini‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,17 @@ commands =
3535
vale sync --config="{toxinidir}/doc/.vale.ini"
3636
vale --config="{toxinidir}/doc/.vale.ini" "{toxinidir}/doc"
3737

38-
[testenv:doc-{links,html}]
38+
[testenv:doc-{clean,links,html,pdf}]
3939
description = Checks documentation links and pages generates properly
40+
allowlist_externals =
41+
pdflatex
4042
extras = doc
4143
setenv =
44+
SOURCE_DIR = doc/source
45+
BUILD_DIR = doc/_build
4246
links: BUILDER = linkcheck
4347
html: BUILDER = html
48+
pdf: BUILDER = latex
49+
links,html,pdf: BUILDER_OPTS = --color -v -j auto -W --keep-going
4450
commands =
45-
sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxinidir}/doc/_build/{env:BUILDER}" --color -v -b {env:BUILDER} -j auto -W --keep-going
51+
links,html,pdf: sphinx-build -d "{toxworkdir}/doc_doctree" {env:SOURCE_DIR} "{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} -b {env:BUILDER}

0 commit comments

Comments
 (0)