Skip to content

Commit 683ac46

Browse files
Revathyvenugopal162jorgepilotoRobPasMue
authored
Add examples of extension libraries. (#191)
* Download all sphinx design examples * Add the examples in doc * Move the scripts * Update ci/cd * Modify workflow * Modify the images * Add additional lines * Add the docs source * Add the scripts inside conf file * Modify workflow * Add the sphinx jinja * Add the sentance case * Add the docstrings * Add example dir * Add the docstrings * remove all warnings * remove all unnecessary files * Update .github/workflows/ci_cd.yml Co-authored-by: Jorge Martínez <[email protected]> * Update doc/source/examples/examples.rst Co-authored-by: Jorge Martínez <[email protected]> * Add the sphinx card * Add the sphinx card ref * Add the table in examples * Typo error * Typo error * Add the sphinx styles * Update src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/js/table.js * Add the table color * Add the toml and arrange css styles * Modify the parameters * Resolves vale error * Add the docs for css * change the docs * change the table * Update .github/workflows/ci_cd.yml --------- Co-authored-by: Jorge Martínez <[email protected]> Co-authored-by: Roberto Pastor Muela <[email protected]>
1 parent d2b32d1 commit 683ac46

File tree

15 files changed

+571
-267
lines changed

15 files changed

+571
-267
lines changed

‎doc/source/conf.py‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22

33
from datetime import datetime
44
import os
5+
from pathlib import Path
6+
from typing import List
57

8+
from bs4 import BeautifulSoup
9+
import requests
610
from sphinx.builders.latex import LaTeXBuilder
711

812
LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
@@ -19,6 +23,10 @@
1923
watermark,
2024
)
2125

26+
THIS_PATH = Path(__file__).parent.resolve()
27+
28+
EXAMPLE_PATH = (THIS_PATH / "examples" / "sphinx_examples").resolve()
29+
2230
# Project information
2331
project = "ansys_sphinx_theme"
2432
copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
@@ -66,6 +74,8 @@
6674
"sphinx.ext.intersphinx",
6775
"notfound.extension",
6876
"sphinx_copybutton",
77+
"sphinx_design",
78+
"sphinx_jinja",
6979
]
7080

7181
# Intersphinx mapping
@@ -128,3 +138,74 @@
128138
"body": generate_404(),
129139
}
130140
notfound_no_urls_prefix = True
141+
142+
143+
def extract_example_links(archive_url: str, exclude_files: List[str]) -> List[str]:
144+
"""
145+
Extract example links from a specific URL.
146+
147+
Parameters
148+
----------
149+
archive_url : str
150+
The URL of the archive to retrieve the example links from.
151+
exclude_files : list of str
152+
A list of files to exclude from the returned example links.
153+
154+
Returns
155+
-------
156+
list
157+
List of example links.
158+
"""
159+
response = requests.get(archive_url)
160+
soup = BeautifulSoup(response.content, "html5lib")
161+
links = soup.find_all("a")
162+
example_links = [
163+
f"https://raw.githubusercontent.com{link['href'].replace('/blob/', '/')}"
164+
for link in links
165+
if link["href"].endswith(".txt") and all(file not in link["href"] for file in exclude_files)
166+
]
167+
return example_links
168+
169+
170+
def download_and_process_files(example_links: List[str]) -> List[str]:
171+
"""Download and process a series of example files.
172+
173+
This function downloads a series of example files using a
174+
list of links and processes each file.
175+
176+
Parameters
177+
----------
178+
example_links : List[str]
179+
List of links to the example files to be downloaded.
180+
181+
Returns
182+
-------
183+
list
184+
List of the names of the processed files.
185+
"""
186+
file_names = []
187+
for link in example_links:
188+
file_name = link.split("/")[-1]
189+
file_path = str((EXAMPLE_PATH / file_name).absolute())
190+
with open(file_path, "wb") as f:
191+
response = requests.get(link)
192+
content = response.content.decode()
193+
lines = content.splitlines()
194+
# Customised only to remove the warnings on docs build.
195+
filtered_lines = [
196+
line
197+
for line in lines
198+
if not line.startswith("Cards Clickable") and not line.startswith("...............")
199+
]
200+
f.write(
201+
b"\n".join([line.replace("target", file_name).encode() for line in filtered_lines])
202+
)
203+
file_names.append(file_name)
204+
return file_names
205+
206+
207+
URL_ARCHIVE = "https://github.com/executablebooks/sphinx-design/tree/main/docs/snippets/rst"
208+
example_links = extract_example_links(URL_ARCHIVE, exclude_files=["article-info.txt"])
209+
file_names = download_and_process_files(example_links)
210+
211+
jinja_contexts = {"examples": {"inputs_examples": file_names}}

‎doc/source/examples/images/particle_background.jpg‎

32.7 KB
Loading

‎doc/source/examples/index.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
========
2+
Examples
3+
========
4+
This show how the different extensions get rendered in ansys-sphinx-theme. This is for testing purpose.
5+
6+
.. grid:: 2
7+
8+
.. grid-item::
9+
.. card:: Sphinx design
10+
:link: sphinx-design
11+
:link-type: ref
12+
13+
Examples of the sphinx design rendered using the `ansys-sphinx-theme`.
14+
15+
.. grid-item::
16+
.. card:: Table
17+
:link: table
18+
:link-type: ref
19+
20+
Examples of tables with JavaScript and RST rendered using the `ansys-sphinx-theme`.
21+
It also recommends improving documentation with RST.
22+
23+
24+
.. toctree::
25+
:hidden:
26+
:maxdepth: 2
27+
28+
sphinx-design
29+
table

‎doc/source/examples/snippet.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
"""Sample functions for ansys-sphinx-theme."""
2+
3+
4+
def func(arg1, arg2):
5+
"""Summary line <should be one one line>.
6+
7+
Extended description of function. Can span multiple lines and
8+
provides a general overview of the function.
9+
10+
.. warning::
11+
Use the ``.. warning::`` directive within the doc-string for any
12+
warnings you would like to explicitly state. For example, if
13+
this method will be deprecated in the next release.
14+
15+
Parameters
16+
----------
17+
arg1 : int
18+
Description of arg1.
19+
arg2 : str
20+
Description of arg2.
21+
22+
Returns
23+
-------
24+
bool
25+
Description of return value.
26+
27+
Examples
28+
--------
29+
>>> func(1, 'foo')
30+
True
31+
32+
"""
33+
return True

‎doc/source/examples/sphinx-design.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. _sphinx-design:
2+
3+
Sphinx design
4+
=============
5+
The rendering of sphinx design with ansys sphinx theme.
6+
To access the full documentation for the sphinx design package,
7+
please refer `sphinx design <https://sphinx-design.readthedocs.io/en/latest/index.html>`_.
8+
9+
.. jinja:: examples
10+
11+
{% for filename in inputs_examples %}
12+
{% set title = filename.split('.')[0] %}
13+
14+
{{ title[0].upper() }}{{ title[1:] }}
15+
{{ '~' * (title | length) }}
16+
17+
.. literalinclude:: sphinx_examples/{{ filename }}
18+
:language: rst
19+
20+
This directive renders the as follow:
21+
22+
.. include:: sphinx_examples/{{ filename }}
23+
24+
{% endfor %}

‎doc/source/examples/sphinx_examples/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
*
2+
!.gitignore

‎doc/source/examples/table.rst‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
.. _table:
2+
3+
Table
4+
=====
5+
The table directive with ansys sphinx theme allows for rendering of tables.
6+
There are different types of tables, such as the data table, longtable-centered,
7+
and table-centered, each serving different purposes.
8+
9+
Data table
10+
----------
11+
This is an example of a data table that can be rendered using the table directive.
12+
It consists of three columns representing the variables A, B, and A and B respectively.
13+
Each row represents a different combination of True and False for variables A and B.
14+
The `datatable` class can be used to style the data table.
15+
16+
.. code:: rst
17+
18+
.. table::
19+
:class: datatable
20+
21+
===== ===== =======
22+
A B A and B
23+
===== ===== =======
24+
False False False
25+
True False False
26+
False True False
27+
True True True
28+
===== ===== =======
29+
30+
.. table::
31+
:class: datatable
32+
33+
===== ===== =======
34+
A B A and B
35+
===== ===== =======
36+
False False False
37+
True False False
38+
False True False
39+
True True True
40+
===== ===== =======
41+
42+
Longtable-centered
43+
------------------
44+
The longtable-centered class can be used to create a table that
45+
spans multiple pages and is centered horizontally.
46+
This is useful for tables that have a large number of rows or columns.
47+
Here is an example of a longtable-centered:
48+
49+
.. code:: rst
50+
51+
.. table::
52+
:class: longtable-centered
53+
54+
+---------------------------+-------------------+
55+
| | MAPDL Command |
56+
+===========================+===================+
57+
| **GUI commands** | * ``*ASK`` |
58+
| | |
59+
| **GUI commands** | * ``*ASK`` |
60+
| | |
61+
| **GUI commands** | * ``*ASK`` |
62+
+---------------------------+-------------------+
63+
64+
.. table::
65+
:class: longtable-centered
66+
67+
+---------------------------+-------------------+
68+
| | MAPDL Command |
69+
+===========================+===================+
70+
| **GUI commands** | * ``*ASK`` |
71+
| | |
72+
| **GUI commands** | * ``*ASK`` |
73+
| | |
74+
| **GUI commands** | * ``*ASK`` |
75+
+---------------------------+-------------------+
76+
77+
Table-centered
78+
--------------
79+
The table-centered class can be used to create a table that is horizontally centered.
80+
This is useful for tables that have only a few columns.
81+
Here is an example of a table-centered:
82+
83+
.. code:: rst
84+
85+
.. table::
86+
:class: table-centered
87+
88+
+---------------------------+-------------------+
89+
| | MAPDL Command |
90+
+===========================+===================+
91+
| **GUI commands** | * ``*ASK`` |
92+
+---------------------------+-------------------+
93+
| **GUI commands** | * ``*ASK`` |
94+
+---------------------------+-------------------+
95+
| **GUI commands** | * ``*ASK`` |
96+
+---------------------------+-------------------+
97+
98+
.. table::
99+
:class: table-centered
100+
101+
+---------------------------+-------------------+
102+
| | MAPDL Command |
103+
+===========================+===================+
104+
| **GUI commands** | * ``*ASK`` |
105+
+---------------------------+-------------------+
106+
| **GUI commands** | * ``*ASK`` |
107+
+---------------------------+-------------------+
108+
| **GUI commands** | * ``*ASK`` |
109+
+---------------------------+-------------------+

‎doc/source/getting_started/index.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,5 +32,3 @@ Consider using the ``conf.py`` for this repository:
3232
.. toctree::
3333
:hidden:
3434
:maxdepth: 2
35-
36-

‎doc/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,4 @@ Ansys Sphinx Theme documentation |version|
1010

1111
getting_started/index.rst
1212
user_guide/index.rst
13+
examples/index.rst

‎doc/styles/Vocab/ANSYS/accept.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,5 @@ ANSYS
22
Ansys
33
ansys
44
Ansys Sphinx Theme
5-
boolean
5+
boolean
6+
datatable

0 commit comments

Comments
 (0)