Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API generation script uses MDX components #1026

Merged
merged 29 commits into from
Apr 3, 2024
Merged

API generation script uses MDX components #1026

Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
59bce17
API generation script uses Function MDX component
arnaucasau Mar 13, 2024
06b72cb
add short name and exceptions
arnaucasau Mar 13, 2024
66227d1
Add all MDX components: class, propery, method, attribute, function, …
arnaucasau Mar 19, 2024
2dba29e
remove h3 and fix signatures
arnaucasau Mar 19, 2024
f50931e
fix method component
arnaucasau Mar 20, 2024
902f7ea
remove backticks and add copyright
arnaucasau Mar 20, 2024
d8a2b95
add back <h3>s
arnaucasau Mar 20, 2024
096e98b
fix method h3
arnaucasau Mar 20, 2024
388accb
incorporate feedback
arnaucasau Mar 21, 2024
e662550
fix signature
arnaucasau Mar 21, 2024
ee08ec2
fix UpperCase
arnaucasau Mar 21, 2024
f966534
remove undefined early return
arnaucasau Mar 22, 2024
ce842a6
change attributeType to attributeTypeHint
arnaucasau Mar 22, 2024
e91d5fd
Merge branch 'main' into AC/generate-Function-component
arnaucasau Mar 25, 2024
4039c0c
fix tests and move github links to prepareProps()
arnaucasau Mar 26, 2024
4c1fe88
Fix inlining
arnaucasau Mar 26, 2024
2ead845
rename tree variable
arnaucasau Mar 26, 2024
a728ebb
escape quotes and remove the unnecessary loop
arnaucasau Mar 27, 2024
f7ed13f
Merge branch 'main' into AC/generate-Function-component
arnaucasau Mar 27, 2024
aceb889
fix snapshot
arnaucasau Mar 27, 2024
2d7c177
Merge branch 'AC/generate-Function-component' of https://github.com/a…
arnaucasau Mar 27, 2024
d3b8195
fix snapshot and move tagName
arnaucasau Mar 27, 2024
8ed2097
fix tests
arnaucasau Mar 27, 2024
03e2fe1
make id optional
arnaucasau Mar 28, 2024
7ceb9ff
fix tests
arnaucasau Mar 28, 2024
3c46a3b
add isDedicatedPage prop and fix historical versions
arnaucasau Apr 2, 2024
92b29d6
fix tests
arnaucasau Apr 2, 2024
5b1c16d
Update scripts/lib/api/mergeClassMembers.ts
arnaucasau Apr 3, 2024
7f67604
early return
arnaucasau Apr 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
266 changes: 119 additions & 147 deletions scripts/lib/api/__snapshots__/conversionPipeline.test.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,107 +54,95 @@ python_api_name: api_example.Electron

# Electron

<span id="api_example.Electron" />
<Class id="api_example.Electron" github="https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example/electron.py" signature="api_example.Electron(size=None, name=None)">
Bases: \`object\`

\`api_example.Electron(size=None, name=None)\` [GitHub](https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example/electron.py "view source code")
A representation of an electron.

Bases: \`object\`
**Examples**

A representation of an electron.
\`\`\`python
from api_example import Electron

**Examples**
ELECTRON = Electron(size="2GB", name="QuantumComputing")
\`\`\`

\`\`\`python
from api_example import Electron
Create an electron.

ELECTRON = Electron(size="2GB", name="QuantumComputing")
\`\`\`
**Parameters**

Create an electron.
* **size** (*str*) – How big should this thing be?
* **name** (*str*) – The name we’ll call the electron. Nicknames preferred.

**Parameters**
**Raises**

* **size** (*str*) – How big should this thing be?
* **name** (*str*) – The name we’ll call the electron. Nicknames preferred.
**ValueError** – You did something wrong

**Raises**
## Attributes

**ValueError** – You did something wrong
### CLASS\\_ATTRIBUTE

## Attributes
<Attribute id="api_example.Electron.CLASS_ATTRIBUTE" name="CLASS_ATTRIBUTE" attributeValue="= re.compile('abc')" />

<span id="api_example.Electron.CLASS_ATTRIBUTE" />
### charge

### CLASS\\_ATTRIBUTE
<Attribute id="api_example.Electron.charge" name="charge" />

\`= re.compile('abc')\`
### mass

<span id="api_example.Electron.charge" />
<Attribute id="api_example.Electron.mass" name="mass">
The mass of the electron.
</Attribute>

### charge
### really\\_long\\_named\\_attribute\\_that\\_probably\\_does\\_not\\_fit\\_nicely

<span id="api_example.Electron.mass" />
<Attribute id="api_example.Electron.really_long_named_attribute_that_probably_does_not_fit_nicely" name="really_long_named_attribute_that_probably_does_not_fit_nicely">
A bit too verbose if you ask me.
</Attribute>

### mass
## Methods

The mass of the electron.
### compute\\_momentum

<span id="api_example.Electron.really_long_named_attribute_that_probably_does_not_fit_nicely" />
<Function id="api_example.Electron.compute_momentum" name="compute_momentum" signature="compute_momentum(velocity)">
Compute the electron’s velocity.

### really\\_long\\_named\\_attribute\\_that\\_probably\\_does\\_not\\_fit\\_nicely
**Parameters**

A bit too verbose if you ask me.
**velocity** (*float*) – The electron’s velocity

## Methods
**Returns**

### compute\\_momentum
The computed momentum.

<span id="api_example.Electron.compute_momentum" />
**Raises**

\`compute_momentum(velocity)\`
**ValueError** – You did something wrong

Compute the electron’s velocity.
**Return type**

**Parameters**
float
</Function>

**velocity** (*float*) – The electron’s velocity
### method\\_with\\_a\\_reallyyreallreallyreallyreallyreallyreallreallyreallyreallyreally\\_long\\_title

**Returns**
<Function id="api_example.Electron.method_with_a_reallyyreallreallyreallyreallyreallyreallreallyreallyreallyreally_long_title" name="method_with_a_reallyyreallreallyreallyreallyreallyreallreallyreallyreallyreally_long_title" signature="method_with_a_reallyyreallreallyreallyreallyreallyreallreallyreallyreallyreally_long_title()">
blahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblah
</Function>

The computed momentum.
### overloaded\\_func

**Raises**
<Function id="api_example.Electron.overloaded_func" name="overloaded_func" signature="overloaded_func(arg1: tuple[str, str], arg2: list[str], arg3: int, arg4: Electron) → None" extraSignatures={['overloaded_func(arg1: tuple[int, int], arg2: list[int], arg3: bool, arg4: set[Electron]) → None']}>
This is meant to test out [https://github.com/Qiskit/qiskit\\_sphinx\\_theme/pull/319](https://github.com/Qiskit/qiskit_sphinx_theme/pull/319).

**ValueError** – You did something wrong
**Parameters**

**Return type**

float

### method\\_with\\_a\\_reallyyreallreallyreallyreallyreallyreallreallyreallyreallyreally\\_long\\_title

<span id="api_example.Electron.method_with_a_reallyyreallreallyreallyreallyreallyreallreallyreallyreallyreally_long_title" />

\`method_with_a_reallyyreallreallyreallyreallyreallyreallreallyreallyreallyreally_long_title()\`

blahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblahblah

### overloaded\\_func

<span id="api_example.Electron.overloaded_func" />

\`overloaded_func(arg1: tuple[str, str], arg2: list[str], arg3: int, arg4: Electron) → None\`

\`overloaded_func(arg1: tuple[int, int], arg2: list[int], arg3: bool, arg4: set[Electron]) → None\`

This is meant to test out [https://github.com/Qiskit/qiskit\\_sphinx\\_theme/pull/319](https://github.com/Qiskit/qiskit_sphinx_theme/pull/319).

**Parameters**

* **arg1** – Tuples ftw!
* **arg2** – But lists are more flexy.
* **arg3** – Primitive values are good too.
* **arg4** – Recursionnnnn.
* **arg1** – Tuples ftw!
* **arg2** – But lists are more flexy.
* **arg3** – Primitive values are good too.
* **arg4** – Recursionnnnn.
</Function>
</Class>

"
`;
Expand All @@ -172,24 +160,22 @@ python_api_name: api_example.my_function

# api\\_example.my\\_function

<span id="api_example.my_function" />

\`api_example.my_function(input1, input2, input3=None, **kwargs)\` [GitHub](https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example.py "view source code")

A function that does awesome stuff.
<Function id="api_example.my_function" github="https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example.py" signature="api_example.my_function(input1, input2, input3=None, **kwargs)">
A function that does awesome stuff.

**Returns**
**Returns**

Did the function work.
Did the function work.

**Raises**
**Raises**

* **ValueError** – If the inputs are not the correct values.
* **TypeError** – If the inputs are not strings.
* **ValueError** – If the inputs are not the correct values.
* **TypeError** – If the inputs are not strings.

**Return type**
**Return type**

int
int
</Function>

"
`;
Expand All @@ -211,106 +197,92 @@ This is a page to test out how we render classes and functions included inline i

Every time you use this program, you’ll want to create an instance of [\`api_example.inline_classes.SimpleInlineClass\`](#api_example.inline_classes.SimpleInlineClass "api_example.inline_classes.SimpleInlineClass"). It has a simple interface:

<span id="api_example.inline_classes.SimpleInlineClass" />
<Class id="api_example.inline_classes.SimpleInlineClass" github="https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example/inline_classes.py" signature="api_example.inline_classes.SimpleInlineClass(arg1)">
This is a simple class that does not have any methods or attributes.

\`api_example.inline_classes.SimpleInlineClass(arg1)\` [GitHub](https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example/inline_classes.py "view source code")

This is a simple class that does not have any methods or attributes.

It only has the class description and constructor. Many classes in Qiskit docs are simple like this.
It only has the class description and constructor. Many classes in Qiskit docs are simple like this.
</Class>

It can be useful to use free functions rather than the class:

###

\`api_example.my_function(input1, input2, input3=None, **kwargs)\` [GitHub](https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example.py "view source code")
<Function id="" github="https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example.py" signature="api_example.my_function(input1, input2, input3=None, **kwargs)">
A function that does awesome stuff.

A function that does awesome stuff.
**Returns**

**Returns**
Did the function work.

Did the function work.
**Raises**

**Raises**
* **ValueError** – If the inputs are not the correct values.
* **TypeError** – If the inputs are not strings.

* **ValueError** – If the inputs are not the correct values.
* **TypeError** – If the inputs are not strings.
**Return type**

**Return type**

int
int
</Function>

Sometimes, you even need to use a really complex class!

<span id="api_example.inline_classes.InlineClassWithMethods" />

\`api_example.inline_classes.InlineClassWithMethods\` [GitHub](https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example/inline_classes.py "view source code")

Bases: \`object\`

This class is more involved.

Note how the methods and attributes are rendered and indented when this class is inlined on the docs page.
<Class id="api_example.inline_classes.InlineClassWithMethods" github="https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example/inline_classes.py" signature="api_example.inline_classes.InlineClassWithMethods">
Bases: \`object\`

## Attributes
This class is more involved.

<span id="api_example.inline_classes.InlineClassWithMethods.CLASS_ATTRIBUTE" />
Note how the methods and attributes are rendered and indented when this class is inlined on the docs page.

### CLASS\\_ATTRIBUTE
## Attributes

\`str\`
### CLASS\\_ATTRIBUTE

\`= 'An important part of any API.'\`
<Attribute id="api_example.inline_classes.InlineClassWithMethods.CLASS_ATTRIBUTE" name="CLASS_ATTRIBUTE" attributeTypeHint="str" attributeValue="= 'An important part of any API.'" />

<span id="api_example.inline_classes.InlineClassWithMethods.interest_rate" />
### interest\\_rate

### interest\\_rate
<Attribute id="api_example.inline_classes.InlineClassWithMethods.interest_rate" name="interest_rate" />

## Methods
## Methods

### method1
### method1

<span id="api_example.inline_classes.InlineClassWithMethods.method1" />
<Function id="api_example.inline_classes.InlineClassWithMethods.method1" name="method1" signature="method1()">
A simple method.

\`method1()\`
**Return type**

A simple method.
int
</Function>

**Return type**
### method2

int
<Function id="api_example.inline_classes.InlineClassWithMethods.method2" name="method2" signature="method2(arg1, arg2, description)">
A method with a lot of args!

### method2
This method will use a Hamiltonian to reach quantum advantage. Hamilton: great play & the secret to quantum computing. What a polymath.

<span id="api_example.inline_classes.InlineClassWithMethods.method2" />
**Parameters**

\`method2(arg1, arg2, description)\`
* **arg1** (*int | float*) – All numbers accepted.
* **arg2** (*list\\[*[*InlineClassWithMethods*](#api_example.inline_classes.InlineClassWithMethods "api_example.inline_classes.InlineClassWithMethods")*]*) – A list of other instances, although these will be discarded.
* **description** (*str*) – If your description is too boring or too cryptic, this program will crash your computer.

A method with a lot of args!
**Return type**

This method will use a Hamiltonian to reach quantum advantage. Hamilton: great play & the secret to quantum computing. What a polymath.

**Parameters**

* **arg1** (*int | float*) – All numbers accepted.
* **arg2** (*list\\[*[*InlineClassWithMethods*](#api_example.inline_classes.InlineClassWithMethods "api_example.inline_classes.InlineClassWithMethods")*]*) – A list of other instances, although these will be discarded.
* **description** (*str*) – If your description is too boring or too cryptic, this program will crash your computer.

**Return type**

tuple\\[int, [*InlineClassWithMethods*](#api_example.inline_classes.InlineClassWithMethods "api_example.inline_classes.InlineClassWithMethods")]
tuple\\[int, [*InlineClassWithMethods*](#api_example.inline_classes.InlineClassWithMethods "api_example.inline_classes.InlineClassWithMethods")]
</Function>
</Class>

### Warning: exceptions

The above APIs might raise an exception! Be careful!

### CustomException

<span id="api_example.inline_classes.CustomException" />

\`api_example.inline_classes.CustomException\` [GitHub](https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example/inline_classes.py "view source code")

See how exceptions render too.
<Class id="api_example.inline_classes.CustomException" name="CustomException" github="https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example/inline_classes.py" signature="api_example.inline_classes.CustomException">
See how exceptions render too.
</Class>

## Other prose

Expand Down Expand Up @@ -357,22 +329,22 @@ Testing internal references… [\`Electron.compute_momentum()\`](api_example.Ele

###

\`api_example.my_function(input1, input2, input3=None, **kwargs)\` [GitHub](https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example.py "view source code")

A function that does awesome stuff.
<Function id="" github="https://github.com/Qiskit/qiskit_sphinx_theme/tree/stable/0.1/api_example.py" signature="api_example.my_function(input1, input2, input3=None, **kwargs)">
A function that does awesome stuff.

**Returns**
**Returns**

Did the function work.
Did the function work.

**Raises**
**Raises**

* **ValueError** – If the inputs are not the correct values.
* **TypeError** – If the inputs are not strings.
* **ValueError** – If the inputs are not the correct values.
* **TypeError** – If the inputs are not strings.

**Return type**
**Return type**

int
int
</Function>

"
`;
Loading