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

Jump to bottom

Remove the includenodoc and customcarditem directives (backport #270) #271

Merged
merged 1 commit into from
May 12, 2023
Merged

Remove the includenodoc and customcarditem directives (backport #270) #271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 1 addition & 3 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@

import qiskit_sphinx_theme
import qiskit_finance
from custom_directives import IncludeDirective, CustomCalloutItemDirective, CustomCardItemDirective
from custom_directives import CustomCalloutItemDirective

# Set env flag so that we can doc functions that may otherwise not be loaded
# see for example interactive visualizations in qiskit.visualization.
Expand Down Expand Up @@ -203,7 +203,5 @@


def setup(app):
app.add_directive("includenodoc", IncludeDirective)
app.add_directive("customcarditem", CustomCardItemDirective)
app.add_directive("customcalloutitem", CustomCalloutItemDirective)
app.setup_extension("versionutils")
129 changes: 3 additions & 126 deletions docs/custom_directives.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,132 +1,9 @@
import os
import re

from docutils.parsers.rst import Directive, directives
from docutils.statemachine import StringList
from docutils import nodes
import re
import os

try:
FileNotFoundError
except NameError:
FileNotFoundError = IOError


class IncludeDirective(Directive):
"""Include source file without docstring at the top of file.

Implementation just replaces the first docstring found in file
with '' once.

Example usage:

.. includenodoc:: /beginner/examples_tensor/two_layer_net_tensor.py

"""

# defines the parameter the directive expects
# directives.unchanged means you get the raw value from RST
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = True
has_content = False
add_index = False

docstring_pattern = r'"""(?P<docstring>(?:.|[\r\n])*?)"""\n'
docstring_regex = re.compile(docstring_pattern)

def run(self):
document = self.state.document
env = document.settings.env
rel_filename, filename = env.relfn2path(self.arguments[0])

try:
text = open(filename).read()
text_no_docstring = self.docstring_regex.sub("", text, count=1)

code_block = nodes.literal_block(text=text_no_docstring)
return [code_block]
except FileNotFoundError as e:
print(e)
return []


class CustomCardItemDirective(Directive):
option_spec = {
"header": directives.unchanged,
"image": directives.unchanged,
"link": directives.unchanged,
"card_description": directives.unchanged,
"tags": directives.unchanged,
}

def run(self):
try:
if "header" in self.options:
header = self.options["header"]
else:
raise ValueError("header not doc found")

if "image" in self.options:
image = "<img src='" + self.options["image"] + "'>"
else:
image = "_static/img/thumbnails/default.png"

if "link" in self.options:
link = self.options["link"]
else:
link = ""

if "card_description" in self.options:
card_description = self.options["card_description"]
else:
card_description = ""

if "tags" in self.options:
tags = self.options["tags"]
else:
tags = ""

except FileNotFoundError as e:
print(e)
return []
except ValueError as e:
print(e)
raise
return []

card_rst = CARD_TEMPLATE.format(
header=header, image=image, link=link, card_description=card_description, tags=tags
)
card_list = StringList(card_rst.split("\n"))
card = nodes.paragraph()
self.state.nested_parse(card_list, self.content_offset, card)
return [card]


CARD_TEMPLATE = """
.. raw:: html

<div class="col-md-12 tutorials-card-container" data-tags={tags}>

<div class="card tutorials-card" link={link}>

<div class="card-body">

<div class="card-title-container">
<h4>{header}</h4>
</div>

<p class="card-summary">{card_description}</p>

<p class="tags">{tags}</p>

<div class="tutorials-image">{image}</div>

</div>

</div>

</div>
"""


class CustomCalloutItemDirective(Directive):
Expand Down