gi-docgen merge requestshttps://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests2023-07-23T21:24:46Zhttps://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/191Draft: templates: Various fixups for list model types2023-07-23T21:24:46ZCorey BerlaDraft: templates: Various fixups for list model typeshttps://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/207Code-highlight c_decl blocks using custom jinja2 filter extension2023-12-08T09:32:29ZFeRD (Frank Dana)Code-highlight c_decl blocks using custom jinja2 filter extensionLike !206 this change was initially undertaken to correct invalid HTML in the generated docs. It... grew a bit, along the way. (Though it does achieve that goal, and much more.)
### c_decl syntax highlighting
The current `gdgenerate.py`...Like !206 this change was initially undertaken to correct invalid HTML in the generated docs. It... grew a bit, along the way. (Though it does achieve that goal, and much more.)
### c_decl syntax highlighting
The current `gdgenerate.py` code attempts to output syntax-highlighted versions of the `c_decl` property for _some_ nodes by defining its value with `utils.code_highlight()`. There are a few issues with that:
1. It has to be careful about doing it, because some nodes' `.c_decl` properties are used to generate _other_ `.c_decl` properties. (e.g. a `func.c_decl` will use `arg.c_decl` for each argument it takes, in generating the declaration string.) So, only wrap leaf nodes.
2. The resulting syntax-highlighted code is then inserted into templates containing `<pre><code>{{ foo.c_decl }}</code></pre>`, resulting in invalid HTML. An example from `method.Window.set_application.html`:
```html
<div class="docblock c-decl">
<pre><code><div class="highlight"><pre><span></span><span class="kt">void</span>
<span class="n">gtk_window_set_application</span><span class="w"> </span><span class="p">(</span>
<span class="w"> </span><span class="n">GtkWindow</span><span class="o">*</span><span class="w"> </span><span class="n">window</span><span class="p">,</span>
<span class="w"> </span><span class="n">GtkApplication</span><span class="o">*</span><span class="w"> </span><span class="n">application</span>
<span class="p">)</span>
</pre></div>
</code></pre>
</div>
</div>
```
`<div><pre><code><div><pre>...</pre></div></code></pre></div>` will never fly -- `<code>` can't contain block elements.
3. And, after all that, joke's on us... the code-highlighting doesn't _work_ anyway, because it uses the default `"highlight"` class and the CSS for pygments uses the markdown extension class of `"codehilite"`.
Item 1 in particular didn't sit right with me — adding highlighting is a presentation function, not a parsing function, so doing it in the generator felt wrong. And anyway, we have this nice templating system for defining presentation.
So, in exactly the _opposite_ approach I used in !206, this MR _removes_ the calls to `utils.code_highlight()` when generating the node data, and instead installs a custom extension in the jinja2 environment, `gidocgen.jinja_extension.HighlightExtension`. That very simple extension creates a new filter for the templating system, `|highlight`, which applies syntax highlighting. So, the templates' code like this:
```html
<div class="docblock">
<pre><code>{{ foo.c_decl }}</code></pre>
</div>
```
instead becomes this:
```html
<div class="docblock">
{{ foo.c_decl|highlight }}
</div>
```
...and pygments' highlighted version of the `foo.c_decl` value is inserted with the correct DOM structure. The filter also sets the pygments `cssclass` parameter to `"codehilite"`, same as the Markdown extension, so the existing CSS for highlighting is applied as expected.<sup>1</sup>
### Style changes
So, that was all well and good, and now the classes' declarations were being output with syntax highlighting as valid HTML.
And it looked terrible.
The existing syntax-highlighting (for code blocks in markdown, as well as the CSS node trees) were using the pygments Solarized themes, both light and dark variants. Solarized is an extremely low-contrast theme which can be _very_ hard to read with certain code, especially its dark variant. So now I had my declarations syntax-highlighted, and they went from Meh to Ew:
### Meh
![image](/uploads/84d90bd2e07ef87c6645524723225c00/image.png)
### Ew
![image](/uploads/7d4d25f77b9820a6e5238664565c6eef/image.png)
So, that's no good at all.
Long story long, I replaced the solarized theme CSS with pygments' `default` and `github-dark` themes for light and dark modes (respectively). Now, the highlighted declarations are not only valid HTML, but they look like this:
![image](/uploads/311a0949f6d50940f87407d524375727/image.png)
![image](/uploads/188b17696b3b590d8d7c04b9b2728ab1/image.png)
(Yay! `\o/`)
#### Notes
1. (Added bonus, with the filter: The pygments lexer applied to the code can be configured both on the jinja environment, by setting `gidocgen_highlight_lexer`, and on a per-use basis by passing an arg to the filter. So, `{{ foo|highlight("java") }}` would highlight `foo` as Java code even if `gidocgen_highlight_lexer` is set to the default `"c"`. ...In _theory_. There's no actual use for that ability, here, so beyond ensuring it didn't break anything I haven't really tested that feature. But it's there, and either works or should be easily fixable.)https://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/210WIP: Various typing fixes for the AST2023-12-08T11:26:57ZFeRD (Frank Dana)WIP: Various typing fixes for the ASTSome initial tweaks to `ast.py`, to address the sort of typing issues that make mypy lose its cool.
Most should (hopefully) be uncontroversial, so far. Things like...
### `typing.Mapping` being used as a concrete type
`Mapping` is an ...Some initial tweaks to `ast.py`, to address the sort of typing issues that make mypy lose its cool.
Most should (hopefully) be uncontroversial, so far. Things like...
### `typing.Mapping` being used as a concrete type
`Mapping` is an abstract type, useful for signatures. But a `dict` variable isn't a `Mapping`, it's a `Dict`. (Just like a `tuple` or a `list` isn't a `Sequence`, though they _are_ both `Sequence` types.)
```python
# This
self._somethings: T.Mapping[str, Something] = {}
# Becomes this
self._somethings: T.Dict[str, Something] = {}
```
### Protecting against property accesses through `None`
One of the most frustrating things about typing (but also why it's useful): If you say your property _can_ be `None`, then you can't access any of _its_ properties without checking first, and you can't use it in any contexts where `None` isn't permitted.
```python
# So, things like...
for foo in things_which_can_be_or_have_None:
some_dict[foo.name] = foo
# Have to be...
some_dict.update({
foo.name: foo
for foo in things_which_can_be_or_have_None
if hasattr(foo, 'name') and foo.name is not None
})
```
#### Other changes
A couple do have logic implications (`super().__contains__(super, foo)` being called, which should just be `super().__contains__(foo)` as the `self` arg is supplied by `super()`), but... they weren't right before.https://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/211template: Add layout for tablet portrait mode2023-12-08T22:11:57ZDenis Washingtontemplate: Add layout for tablet portrait modeAt typical tablet portait mode resolutions, the content is uncomfortably
narrow. Fix this by hiding the table of contents, as well as slightly
narrowing the sidebar, which gives the content much more room.
Also, fix a typo in the existi...At typical tablet portait mode resolutions, the content is uncomfortably
narrow. Fix this by hiding the table of contents, as well as slightly
narrowing the sidebar, which gives the content much more room.
Also, fix a typo in the existing styles for phone-sized screens
(`display: hidden` -> `display: none`).
Fixes: #95
__Before:__
![Bildschirmfoto_2023-12-08_um_23.03.47](/uploads/f274ad4a1e3a1a77379cb58a5d7e13cf/Bildschirmfoto_2023-12-08_um_23.03.47.png)
__After:__
![Bildschirmfoto_2023-12-08_um_23.11.11](/uploads/8a2af4118b9899b234811f1cb93ace01/Bildschirmfoto_2023-12-08_um_23.11.11.png)https://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/209Various small HTML fixes2023-12-16T12:15:30ZFeRD (Frank Dana)Various small HTML fixesThese fixes are the result of running HTML Tidy on the output of `gi-docgen generate -C examples/gtk4.html /usr/share/gir-1.0/Gtk-4.0.gir`, and fixing whatever was causing HTML errors in the generated output. With these fixes in place, T...These fixes are the result of running HTML Tidy on the output of `gi-docgen generate -C examples/gtk4.html /usr/share/gir-1.0/Gtk-4.0.gir`, and fixing whatever was causing HTML errors in the generated output. With these fixes in place, Tidy is completely happy with the generated docs _except_ for three issues:
1. A bare HTML tag in the documentation source for `class.Label.html`, which I submitted GNOME/gtk!6650 to fix
1. A tag conflict specific to `class.Builder.html`, where the embedded Markdown contains a heading "Properties" that receives an `id="properties"` attribute, which then conflicts with one of gi-docgen's own headings farther down. Not sure how to best fix that one.
1. The embedded SVG source for the hierarchy diagrams. They no longer contain the leading `DOCTYPE` and `xml` tags that Tidy objected to (I added code to strip those off), but they still use `pt` units for the `width` and `height` attributes of the `<svg>` tag, which Tidy doesn't seem to like.https://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/203Expand sigil replacement for functions, enum values2023-12-20T15:51:15ZFeRD (Frank Dana)Expand sigil replacement for functions, enum valuesThis MR contains three commits, all of which modify `gidocgen/mdext.py`.
1. Create a `SigilReplacement` class which handles the replacement of sigil strings in the documentation, encapsulating both the pattern and replacement strings to...This MR contains three commits, all of which modify `gidocgen/mdext.py`.
1. Create a `SigilReplacement` class which handles the replacement of sigil strings in the documentation, encapsulating both the pattern and replacement strings together into a single object for readability. All of the existing patterns and replacements are converted into `SigilReplacement` instances which are stored in a tuple, then applied in order programmatically. This is entirely a code-readability / quality-of-life change.
2. Adjust the `SigilReplacement("Function")` pattern so that functions followed by punctuation will be matched and processed. Previously, this would be matched:
```text
Call gtk_image_new_from_icon_name() to construct.
```
But this would not:
```text
Call gtk_image_new_from_icon_name(), the constructor.
```
3. Add a `SigilReplacement("Enum")` to match enum values, which previously were not being replaced.
The last change can help avoid MarkDown parsing disasters like the following (from the live Gtk3 docs):
![image](/uploads/b5bc21109df96bad083fec95d9dc7f00/image.png)
With the code in this MR, that becomes:
![image](/uploads/0124f3244aeed9ef7f9b0f9bd1b95f27/image.png)https://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/213generate: Add earliest_version option for since tags2024-01-11T10:35:28ZMichael Catanzarogenerate: Add earliest_version option for since tagsThis improves the strategy introduced in !198. By default, if a Since
tag is not present on an API, we assume the version to use matches the
API version. But this doesn't work for projects where API version
doesn't match the project majo...This improves the strategy introduced in !198. By default, if a Since
tag is not present on an API, we assume the version to use matches the
API version. But this doesn't work for projects where API version
doesn't match the project major version, so add a new earliest_version
option to allow overriding this heuristic.
Fixes #179https://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/220types: Don't generate classes hierarchy if not needed2024-01-27T12:47:19ZBilal Elmoussaouibil.elmoussaoui@gmail.comtypes: Don't generate classes hierarchy if not neededIn case the library doesn't have any gobjects, there would be no classes
hierarchy to render. In such case, go ahead and even hide the additional documents
section
Basically, I want to get rid of https://gnome.pages.gitlab.gnome.org/mut...In case the library doesn't have any gobjects, there would be no classes
hierarchy to render. In such case, go ahead and even hide the additional documents
section
Basically, I want to get rid of https://gnome.pages.gitlab.gnome.org/mutter/mtk/#extrahttps://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/222utils: Append period after last line in more cases2024-02-05T03:07:59ZMatthijs Velsinkmvelsink@gnome.orgutils: Append period after last line in more casesAfter the last line in a block, gi-docgen appends a period. Obviously,
this should not happen when there is already a period. This is handled
by testing for `isalpha()` on the last character.
However, periods should also be inserted aft...After the last line in a block, gi-docgen appends a period. Obviously,
this should not happen when there is already a period. This is handled
by testing for `isalpha()` on the last character.
However, periods should also be inserted after links or inline code. Fix
this by broadening the cases in which a period is appended.
Fixes #181
See https://docs.gtk.org/glib/func.strdelimit.html (`delimiters` parameter) and https://docs.gtk.org/glib/func.strconcat.html (`string1` parameter) for examples where a period would need to be appended.
I cannot think of more instances where a period would break syntax, but those would be easy to add to the exceptions in this MR.https://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/224utils: Find dot instead of assuming it's in PATH2024-02-18T17:56:04ZEmmanuele Bassiutils: Find dot instead of assuming it's in PATHThe result of find_program() is memoized, so we can call it multiple
times.The result of find_program() is memoized, so we can call it multiple
times.Emmanuele BassiEmmanuele Bassihttps://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/216Draft: Add mermaid.js support to the Markdown parser2024-03-11T11:19:57ZEmmanuele BassiDraft: Add mermaid.js support to the Markdown parserUse a local Markdown extension that identifies code blocks using the
Mermaid identifier, and expands them to a `<pre>...</pre>` block without
code highlighting, so that mermaid.js can do its job.
FIXME: the embedded mermaid.js doesn't w...Use a local Markdown extension that identifies code blocks using the
Mermaid identifier, and expands them to a `<pre>...</pre>` block without
code highlighting, so that mermaid.js can do its job.
FIXME: the embedded mermaid.js doesn't work locally, but it does work
when pointing the `<style>` element to the mermaid CDN. Need to figure out
why.
Fixes: #180Emmanuele BassiEmmanuele Bassihttps://gitlab.gnome.org/GNOME/gi-docgen/-/merge_requests/225utils: Only consider dot data processing fail if dot returns non-zero2024-03-11T12:07:36ZXi Ruoyaoxry111@xry111.siteutils: Only consider dot data processing fail if dot returns non-zerodot can output some warnings but still generate the svg output. For
example, when Graphviz is not built with Pango or the system has no font
installed, dot can complain
Warning: no hard-coded metrics for 'sans-serif'
but still gen...dot can output some warnings but still generate the svg output. For
example, when Graphviz is not built with Pango or the system has no font
installed, dot can complain
Warning: no hard-coded metrics for 'sans-serif'
but still generate the svg. The return code of dot allows us to
distinguish errors and warnings, so we can stop treating warnings as
hard errors.
I've checked the visualized class hierarchy graphs of glib-2.80.0 with
this change applied to gi-docgen, and a Graphviz built w/o Pango. The
graphs still look fine.
Fixes #188.