I would like to extend the built-in sphinx-doc extension sphinx.ext.graphviz with a few featues. As the features are very special for my use case i do not want to extend sphinx.ext.graphviz itself.
Essentially i just want to (graphviz sources for reference)
parse with graphviz to get the graphviz nodes (~ Graphviz.run()),
modify the graphviz dotcode of the nodes (~ node['code'] = dotcode),
output/render (html/pdf) with graphviz without modification (~ e.g. for
html: html_visit_graphviz() -> render_dot_html()).
I have read the sphinx-doc extension developer guide but do not fully
understand the build phases/procedure and how to "combine" extensions like described above.
Is it possible to modifiy the inlined graphviz code between "Build Phase
1: Reading" and "Build Phase 3: Resolving" somehow using an additional
sphinx extension which "invokes" sphinx.ext.graphviz?
The solution provided by a sphinx-doc contributor [https://github.com/sphinx-doc/sphinx/issues/2246]:
Maybe you can do it with following code:
def on_doctree_read(app, doctree):
for node in doctree.traverse(graphviz):
code = re.sub('\];', ', color = red];', node['code']) # change color of nodes and edges
node['code'] = code
def setup(app):
app.connect('doctree-read', on_doctree_read)
In this example, I used the doctree-read event. It is raised at Reading phase. In more detail, you can see what is "Sphinx core events" at http://www.sphinx-doc.org/en/stable/extdev/appapi.html#sphinx-core-events
Related
I have a graphviz code like this:
import pygraphviz as pgv
A = pgv.AGraph(strict=False, directed=True,
overlap=False, sep="+10,10")
[A.add_node(k) for k, v in S] # adding all nodes
A.add_edge(S.created, S.packaged_unassigned)
A.add_edge(S.packaged_unassigned, S.packaged_assigned)
A.add_edge(S.packaged_assigned, S.packaged_unassigned, style="dotted")
A.add_edge(S.packaged_assigned, S.shipped_to_distributor)
A.add_edge(S.shipped_to_distributor, S.on_distributor_side_out)
A.add_edge(S.on_distributor_side_out, S.shipped_to_deployer)
A.add_edge(S.shipped_to_deployer, S.on_distributor_side_in)
A.add_edge(S.on_distributor_side_in, S.shipped_to_lab)
A.add_edge(S.shipped_to_lab, S.on_lab_side)
A.add_edge(S.on_lab_side, S.analysis_completed)
A.add_edge(S.analysis_completed, S.completed)
A.layout()
A.draw("status_chart.png")
which produces this output:
https://i.ibb.co/7pJQ8rd/Screenshot-2020-12-20-at-22-23-10.png
My concern here is that the nodes seem to not utilize the available space properly. Instead they just span the diagonal of the image.
How can i make graphviz utilize the space better to create a smaller image while keeping the constraint of no overlaps?
One constraint is that you have specified a chained graph. and thus, the plot is somewhat constrained by that.
See the documentation for some possible alternative options to specify:
https://pygraphviz.github.io/documentation/latest/reference/agraph.html
For example, you can try specifying a landscape view
AGraph(landscape='true'...)
You can also try experimenting with different layout directives:
Optional prog=[‘neato’|’dot’|’twopi’|’circo’|’fdp’|’nop’] will use specified graphviz layout method.
Also see:
unflatten(args='')
To adjust directed graphs to improve layout aspect ratio.
Another technique you could use is to break-up parts of the graph, such that it might look like this (adding a text label to the nodes, with the numbering scheme):
(1) -> (2) ->(3)
(4) -> (5) ->(6)
...
NOTE: The Python documentation for that library specifically suggests that you also refer to the Graphviz documentation...for additional options.
http://www.graphviz.org/doc/info/lang.html
http://www.graphviz.org/doc/info/attrs.html
For example:
http://www.graphviz.org/doc/info/attrs.html#d:ratio
http://www.graphviz.org/doc/info/attrs.html#a:layout
http://www.graphviz.org/doc/info/attrs.html#d:scale
The Gallery also has some great examples, illustrating the use of different parameters
http://www.graphviz.org/gallery/
I've noticed that when I use autodoc with the ReadTheDoc theme, if I have multiple arguments in my functions they are listed in a bullet list style:
arg1
arg2
...
but if there is only 1 argument then it is not using the bullet list style which is a bit silly to me since it breaks the continuity of the design.
I've found how to remove the disc via CSS to make things more uniform but I actually want to do the opposite and have the disk for the single argument functions.
At this point, I'm not sure it is a CSS change and I do not know how to do that.
I've also noticed the same thing in different docs.
Here is the rendered html:
Here are the 2 methods:
def add_attribute(self, name, index):
"""
:param name: The name attached to the attribute.
:param index: The position of the attribute within the list of attributes. """
print("")
def delete_attribute(self, name):
"""
:param name: The name of the attribute to delete."""
print("")
Here is the my .rst:
API
----------------
.. automodule:: my_module
:members:
Here is the conf.py
extensions = [
'sphinx_rtd_theme',
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.coverage',
'sphinx.ext.autosummary',
]
templates_path = ['_templates']
language = 'python'
exclude_patterns = []
html_theme = "sphinx_rtd_theme"
html_static_path = ['_static']
autosummary_generate = True
Any idea?
Cheers!
After a lot of digging, I've found a partial workaround for this.
My solution involves manually editing the produced HTML files to insert the missing bullet points.
Required conf.py changes:
# Register hook to run when build is complete
def setup(app):
app.connect('build-finished', on_build_finished)
# Hook implementation
def on_build_finished(app, exception):
add_single_param_bullets("_build/html/index.html")
# Function to actually add the bullet points by overwriting the given HTML file
def add_single_param_bullets(file_path):
print('Add single parameter bullets in {:s}'.format(file_path))
if not os.path.exists(file_path):
print(' File not found, skipping...')
return
lines_enc = []
with open(file_path, 'rb') as f:
for l in f.readlines():
# Check for html that indicates single parameter function
if b'<dd class="field-odd"><p><strong>' in l:
# Work out the encoding if not defined
enc = None
if enc is None:
import chardet
enc = chardet.detect(l)['encoding']
# Decode html and get the parameter information that needs adding
l_dec = l.decode(enc)
l_insert = l_dec.replace('<dd class="field-odd">', '').replace('\r\n', '')
# Add new encoded lines to output
lines_enc.append('<dd class="field-odd"><ul class="simple">'.encode('utf=8'))
lines_enc.append('<li>{:s}</li>'.format(l_insert).encode(enc))
lines_enc.append('</ul>'.encode('utf=8'))
else:
lines_enc.append(l)
# Overwrite the original file with the new changes
with open(file_path, 'wb') as f:
for l in lines_enc:
f.write(l)
In my case, I only have single argument functions in index.html. However, you can register additional files in on_build_finished.
A few things to note:
This only edits the produced HTML files, and doesn't actually solve the underlying problem. I dug through the source for a bit but couldn't find why the bullet points aren't added for single parameter function.
The problem is not just for the RTD theme. It seems to occur with the basic theme as well. So I suspect it's a deeper problem with Sphinx rather than the RTD theme.
The code above somewhat deals with different encodings in the original HTML.
This does not work on the RTD website. As the HTML files are edited in place, and the RTD build outputs the HTML files to a different directory, this solution doesn't seem to work on the RTD website. This is quite annoying. A solution would be to somehow change the RTD build process, or tell RTD to use pre-built HTML sources rather than building its own, but I don't know how to do so.
After spending a few hours working all this out, I actually think it looks better without the bullet points...
I tried turning on Sphinx's nit-picky mode (-n) to catch any broken links I might have accidentally made. However, it spews out errors for all the places where I've documented types. In some cases I've described types semantically (e.g. "3D array"), but it does it even for types extracted from type hints (even with intersphinx set up to pull Python types). For example, for this module
from typing import Callable
def foo(x: Callable[..., int]):
pass
I get the error docstring of myproj.foo:: WARNING: py:class reference target not found: Callable[..., int]. That's with only sphinx.ext.autodoc and sphinx.ext.intersphinx extensions and a freshly-generated conf.py.
Is there some way to prevent Sphinx from trying to generate links for type information, or at least stop it complaining when they don't exist while still telling me about bad links in my hand-written documentation?
I'm using Sphinx 3.0.3.
Perhaps nitpick_ignore will do what you want? In your conf.py, something like this:
nitpick_ignore = [
("py:class", "Callable"),
]
I'm not sure of the exact values in the tuple that should be used, but I got the idea from this issue and a linked commit.
I had success solving a similar problem by writing a custom sphinx transform. I only wanted warnings for cross-references to my own package's python documentation. The following can be saved as a python file and added to extensions in conf.py once it is on the python path.
from sphinx import addnodes
from sphinx.errors import NoUri
from sphinx.transforms.post_transforms import SphinxPostTransform
from sphinx.util import logging
logger = logging.getLogger(__name__)
class MyLinkWarner(SphinxPostTransform):
"""
Warns about broken cross-reference links, but only for my_package_name.
This is very similar to the sphinx option ``nitpicky=True`` (see
:py:class:`sphinx.transforms.post_transforms.ReferencesResolver`), but there
is no way to restrict that option to a specific package.
"""
# this transform needs to happen before ReferencesResolver
default_priority = 5
def run(self):
for node in self.document.traverse(addnodes.pending_xref):
target = node["reftarget"]
if target.startswith("my_package_name."):
found_ref = False
with suppress(NoUri, KeyError):
# let the domain try to resolve the reference
found_ref = self.env.domains[node["refdomain"]].resolve_xref(
self.env,
node.get("refdoc", self.env.docname),
self.app.builder,
node["reftype"],
target,
node,
nodes.TextElement("", ""),
)
# warn if resolve_xref did not return or raised
if not found_ref:
logger.warning(
f"API link {target} is broken.", location=node, type="ref"
)
def setup(app):
app.add_post_transform(MyLinkWarner)
Long story short, when I thought the strings would be translated, nothing happens.
I have a PyGtk application and a module where I store all the strings that I want to be translated in the following way:
'''
Strings module.
'''
....
CANCEL_BUTTON_TEXT = _("Cancel")
BACK_BUTTON_TEXT = _("Back")
....
And so on. So then they are used from other modules like:
'''
View module.
'''
import strings
# Usage example
button.set_label(strings.CANCEL_BUTTON_TEXT)
button.set_tooltip(strings.TOOLTIP)
window_title.set_title(strings.WINDOW_TITLE)
...
I have created the necessary .mo files. This is the jerarquy I have:
/locales
/es
LC_MESSAGES
base.mo
base.po
/en
LC_MESSAGES
base.mo
base.po
base.pot
As the documentation says (https://docs.python.org/3/library/gettext.html), in my main.py I have the following lines:
import gettext
gettext.install('myapplication')
es_lang = gettext.translation('base', localedir='locales', languages=['es'])
en_lang = gettext.translation('base', localedir='locales', languages=['en'])
es_lang.install()
Then, in my application I have a button, that when is pressed, the following line is executed:
en_lang.install()
But the spanish language is still used on the widgets. Could anyone help me out?
So, what I was doing wrong is I was translating the strings but I wasn't updating the GTK Widgets labels, among other things.
The way I solved this was:
i) Created a class where I put all the strings I want to translate when the user selects a language. That class is the only one to import the gettext module.
ii) When the user selects a language, a method of that class is called and it translates all strings to that language.
iii) Another method outside that class updates all labels and widgets that use those strings.
I need a numerical example which demonstrates the working of clustering using CURE algorithm.
https://www.cs.ucsb.edu/~veronika/MAE/summary_CURE_01guha.pdf
The pyclustering library has a number of clustering algorithims with examples, and example code on their Github. Here is a link the CURE example.
Googling Cure algorithim example also came up with a fair bit.
Hopefully that helps!
Using pyclustering library you can extract information about representatives points and means using corresponding methods (link to CURE pyclustering generated documentation):
# create instance of the algorithm
cure_instance = cure(<algorithm parameters>);
# start processing
cure_instance.process();
# get allocated clusteres
clusters = cure_instance.get_clusters();
# get representative points
representative = cure_instance.get_representors();
Also you can modify source code of the CURE algorithm to display changes after each step, for example, print them to console or even visualize. Here is an example how to modify code to display changes on each step clustering (after line 219) where star means representative point, small points - points itself and big points - means:
# New cluster and updated clusters should relocated in queue
self.__insert_cluster(merged_cluster);
for item in cluster_relocation_requests:
self.__relocate_cluster(item);
#
# ADD FOLLOWING PEACE OF CODE TO DISPLAY CHANGES ON EACH STEP
#
temp_clusters = [ cure_cluster_unit.indexes for cure_cluster_unit in self.__queue ];
temp_representors = [ cure_cluster_unit.rep for cure_cluster_unit in self.__queue ];
temp_means = [ cure_cluster_unit.mean for cure_cluster_unit in self.__queue ];
visualizer = cluster_visualizer();
visualizer.append_clusters(temp_clusters, self.__pointer_data);
for cluster_index in range(len(temp_clusters)):
visualizer.append_cluster_attribute(0, cluster_index, temp_representors[cluster_index], '*', 7);
visualizer.append_cluster_attribute(0, cluster_index, [ temp_means[cluster_index] ], 'o');
visualizer.show();
You will see sequence of images, something like that:
Thus, you can display any information that you need.
Also I would like to add that you can use C++ implementation of the algorithm for visualization (that is also part of pyclustering): https://github.com/annoviko/pyclustering/blob/master/ccore/src/cluster/cure.cpp