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.

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

docs: Fix basic rst formatting errors #2958

Merged
merged 8 commits into from
May 1, 2024

Conversation

jvesely
Copy link
Collaborator

@jvesely jvesely commented Apr 28, 2024

Fix the following warnings:
WARNING: Malformed table. (3 instances)
WARNING: Title underline too short. (13 instances)
WARNING: Inline strong start-string without end-string. (31 instances)
WARNING: Inline literal start-string without end-string. (1 instance)
WARNING: Inline emphasis start-string without end-string. (2 instances)
WARNING: Unknown target name (3 instances)
WARNING: Inline interpreted text or phrase reference start-string without end-string. (31 instances)
WARNING: Inline substitution_reference start-string without end-string. (1 instance)

The above removes 61/81 instances of <span class="problematic"> in the generated html.

@jvesely jvesely added the documentation Documentation text label Apr 28, 2024
@jvesely jvesely requested review from davidt0x, kmantel and jdcpni April 28, 2024 00:48
@jvesely
Copy link
Collaborator Author

jvesely commented Apr 28, 2024

The remaining 20 issues causing "problematic" are in the following files:

build/html/Condition.html
build/html/Defaults.html
build/html/globals.html
build/html/nback_nb.html

build/html/Condition.html -- should be fixable in the graph_scheduler package.
build/html/Defaults.html and build/html/globals.html -- an experiment in printing the value of defaultAllocation
build/html/nback_nb.html -- misrepresented python code in notebook.

Copy link

This PR causes the following changes to the html docs (ubuntu-latest-3.11):

diff -r docs-base/AutoAssociativeLearningMechanism.html docs-head/AutoAssociativeLearningMechanism.html
266c266
< * 1) its execution can be enabled or disabled by setting the <a href="#id1"><span class="problematic" id="id2">`</span></a>learning_enabled</p>
---
> * 1) its execution can be enabled or disabled by setting the <a class="reference internal" href="RecurrentTransferMechanism.html#psyneulink.library.components.mechanisms.processing.transfer.recurrenttransfermechanism.RecurrentTransferMechanism.learning_enabled" title="psyneulink.library.components.mechanisms.processing.transfer.recurrenttransfermechanism.RecurrentTransferMechanism.learning_enabled"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">learning_enabled</span></code></a></p>
268,269c268,269
< <div><p>&lt;RecurrentTransferMechanism.learning_enabled&gt;` attribute of the <a class="reference internal" href="RecurrentTransferMechanism.html"><span class="doc">RecurrentTransferMechanism</span></a> with which it is
< associated (identified in its <a class="reference internal" href="#psyneulink.library.components.mechanisms.modulatory.learning.autoassociativelearningmechanism.AutoAssociativeLearningMechanism.activity_source" title="psyneulink.library.components.mechanisms.modulatory.learning.autoassociativelearningmechanism.AutoAssociativeLearningMechanism.activity_source"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">activity_source</span></code></a> attribute).</p>
---
> <div><p>attribute of the <a class="reference internal" href="RecurrentTransferMechanism.html"><span class="doc">RecurrentTransferMechanism</span></a> with which it is associated (identified in its
> <a class="reference internal" href="#psyneulink.library.components.mechanisms.modulatory.learning.autoassociativelearningmechanism.AutoAssociativeLearningMechanism.activity_source" title="psyneulink.library.components.mechanisms.modulatory.learning.autoassociativelearningmechanism.AutoAssociativeLearningMechanism.activity_source"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">activity_source</span></code></a> attribute).</p>
diff -r docs-base/AutodiffComposition.html docs-head/AutodiffComposition.html
328c328
< <p>This is the default for an AutodiffComposition, but, can be specified explicitly by setting <a href="#id1"><span class="problematic" id="id2">**</span></a>execution_mode =
---
> <p>This is the default for an AutodiffComposition, but, can be specified explicitly by setting <strong>execution_mode</strong> =
diff -r docs-base/Component.html docs-head/Component.html
327c327
< <a href="#id2"><span class="problematic" id="id3">`shape &lt;https://numpy.org/doc/stable/reference/generated/numpy.shape.html&gt; in Numpy`_</span></a>, with the difference that
---
> <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.shape.html">shape in Numpy</a>, with the difference that
diff -r docs-base/Composition.html docs-head/Composition.html
425,426c425,426
< <div><ul>
< <li><dl>
---
> <div><ul class="simple">
> <li><dl class="simple">
431,434c431
< it can be useful for custom configurations, including the implementation of specific Projection <a href="#id1"><span class="problematic" id="id2">`</span></a>matrices</p>
< <blockquote>
< <div><p>&lt;MappingProjection.matrix&gt;`.</p>
< </div></blockquote>
---
> it can be useful for custom configurations, including the implementation of specific Projection <a class="reference internal" href="MappingProjection.html#psyneulink.core.components.projections.pathway.mappingprojection.MappingProjection.matrix" title="psyneulink.core.components.projections.pathway.mappingprojection.MappingProjection.matrix"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">matrices</span></code></a>.</p>
550c547
< <span id="id3"></span><h2>Composition Structure<a class="headerlink" href="#composition-structure" title="Permalink to this headline">¶</a></h2>
---
> <span id="id1"></span><h2>Composition Structure<a class="headerlink" href="#composition-structure" title="Permalink to this headline">¶</a></h2>
626,628c623,625
< outer Composition, are assigned <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> in addition to their other <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole" title="psyneulink.core.compositions.composition.NodeRole"><code class="xref any py py-class docutils literal notranslate"><span class="pre">roles</span></code></a> in the
< nested Composition. The only difference between <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Nodes
< is whether their output is included in the <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> attributes of the <em>outermost</em> Composition to which they project; this is determined by the
---
> outer Composition, are assigned <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> in addition to their other <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole" title="psyneulink.core.compositions.composition.NodeRole"><code class="xref any py py-class docutils literal notranslate"><span class="pre">roles</span></code></a> in the
> nested Composition. The only difference between <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Nodes
> is whether their output is included in the <a class="reference internal" href="#id9" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> attributes of the <em>outermost</em> Composition to which they project; this is determined by the
631c628
< <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes are <em>not</em> included in the <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> or <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> for the outermost Composition to which they project (although they <em>are</em> still included
---
> <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes are <em>not</em> included in the <a class="reference internal" href="#id9" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> or <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> for the outermost Composition to which they project (although they <em>are</em> still included
635c632
< <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.include_probes_in_output" title="psyneulink.core.compositions.composition.Composition.include_probes_in_output"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">include_probes_in_output</span></code></a> is True, then any <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes
---
> <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.include_probes_in_output" title="psyneulink.core.compositions.composition.Composition.include_probes_in_output"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">include_probes_in_output</span></code></a> is True, then any <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes
637,638c634,635
< the <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> of the outermost Composition.
< <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes can be visualized, along with any Projections treated differently from those of
---
> the <a class="reference internal" href="#id9" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> of the outermost Composition.
> <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes can be visualized, along with any Projections treated differently from those of
646c643
< <div><p><a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes are useful for <a class="reference internal" href="OptimizationControlMechanism.html#optimizationcontrolmechanism-model-based"><span class="std std-ref">model-based optimization using an</span></a>, in which the value of one or more Nodes in a nested Composition
---
> <div><p><a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes are useful for <a class="reference internal" href="OptimizationControlMechanism.html#optimizationcontrolmechanism-model-based"><span class="std std-ref">model-based optimization using an</span></a>, in which the value of one or more Nodes in a nested Composition
666c663
< <p>A Node can be both a <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> and an <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Node of a nested Composition,
---
> <p>A Node can be both a <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> and an <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Node of a nested Composition,
670c667
< (those are treated in the same way as <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes).</p>
---
> (those are treated in the same way as <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes).</p>
682c679
< both the <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> of the nested Composition
---
> both the <a class="reference internal" href="#id9" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> of the nested Composition
684c681
< <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class
...

See CI logs for the full diff.

@jvesely
Copy link
Collaborator Author

jvesely commented Apr 28, 2024

The HTML documentation with the fixes is available at [0]
e.g. the malformed table in "Comparison of learning modes" is absent from the documentation [1], but it is displayed correctly after the fixes are applied [2].

[0] https://jvesely.github.io/PsyNeuLink/branch/docs/
[1] https://princetonuniversity.github.io/PsyNeuLink/Composition.html#comparison-of-learning-modes
[2] https://jvesely.github.io/PsyNeuLink/branch/docs/Composition.html#comparison-of-learning-modes

jvesely added 8 commits April 30, 2024 20:59
Fixes 3 instances of:
WARNING: Malformed table.

Signed-off-by: Jan Vesely <[email protected]>
Fixes 13 instances of:
WARNING: Title underline too short.

Signed-off-by: Jan Vesely <[email protected]>
Fixes 31 instances of:
WARNING: Inline strong start-string without end-string.

There are 6 remaining instances that all come from:
psyneulink.core.scheduling.condition
imported from graph_scheduler

Signed-off-by: Jan Vesely <[email protected]>
Fixes one instance of:
WARNING: Inline literal start-string without end-string.

Signed-off-by: Jan Vesely <[email protected]>
Fixes two instances of:
WARNING: Inline emphasis start-string without end-string.
The remaining instances are imported from schedulin.condition.

Signed-off-by: Jan Vesely <[email protected]>
Fixes 3 instances of:
WARNING: Unknown target name:

Signed-off-by: Jan Vesely <[email protected]>
Fixes 31 instances of:
WARNING: Inline interpreted text or phrase reference start-string without end-string.

Signed-off-by: Jan Vesely <[email protected]>
Fixes one instance of:
WARNING: Inline substitution_reference start-string without end-string.

Signed-off-by: Jan Vesely <[email protected]>
Copy link

github-actions bot commented May 1, 2024

This PR causes the following changes to the html docs (ubuntu-latest-3.11):

diff -r docs-base/AutoAssociativeLearningMechanism.html docs-head/AutoAssociativeLearningMechanism.html
266c266
< * 1) its execution can be enabled or disabled by setting the <a href="#id1"><span class="problematic" id="id2">`</span></a>learning_enabled</p>
---
> * 1) its execution can be enabled or disabled by setting the <a class="reference internal" href="RecurrentTransferMechanism.html#psyneulink.library.components.mechanisms.processing.transfer.recurrenttransfermechanism.RecurrentTransferMechanism.learning_enabled" title="psyneulink.library.components.mechanisms.processing.transfer.recurrenttransfermechanism.RecurrentTransferMechanism.learning_enabled"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">learning_enabled</span></code></a></p>
268,269c268,269
< <div><p>&lt;RecurrentTransferMechanism.learning_enabled&gt;` attribute of the <a class="reference internal" href="RecurrentTransferMechanism.html"><span class="doc">RecurrentTransferMechanism</span></a> with which it is
< associated (identified in its <a class="reference internal" href="#psyneulink.library.components.mechanisms.modulatory.learning.autoassociativelearningmechanism.AutoAssociativeLearningMechanism.activity_source" title="psyneulink.library.components.mechanisms.modulatory.learning.autoassociativelearningmechanism.AutoAssociativeLearningMechanism.activity_source"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">activity_source</span></code></a> attribute).</p>
---
> <div><p>attribute of the <a class="reference internal" href="RecurrentTransferMechanism.html"><span class="doc">RecurrentTransferMechanism</span></a> with which it is associated (identified in its
> <a class="reference internal" href="#psyneulink.library.components.mechanisms.modulatory.learning.autoassociativelearningmechanism.AutoAssociativeLearningMechanism.activity_source" title="psyneulink.library.components.mechanisms.modulatory.learning.autoassociativelearningmechanism.AutoAssociativeLearningMechanism.activity_source"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">activity_source</span></code></a> attribute).</p>
diff -r docs-base/AutodiffComposition.html docs-head/AutodiffComposition.html
328c328
< <p>This is the default for an AutodiffComposition, but, can be specified explicitly by setting <a href="#id1"><span class="problematic" id="id2">**</span></a>execution_mode =
---
> <p>This is the default for an AutodiffComposition, but, can be specified explicitly by setting <strong>execution_mode</strong> =
diff -r docs-base/Component.html docs-head/Component.html
327c327
< <a href="#id2"><span class="problematic" id="id3">`shape &lt;https://numpy.org/doc/stable/reference/generated/numpy.shape.html&gt; in Numpy`_</span></a>, with the difference that
---
> <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.shape.html">shape in Numpy</a>, with the difference that
diff -r docs-base/Composition.html docs-head/Composition.html
425,426c425,426
< <div><ul>
< <li><dl>
---
> <div><ul class="simple">
> <li><dl class="simple">
431,434c431
< it can be useful for custom configurations, including the implementation of specific Projection <a href="#id1"><span class="problematic" id="id2">`</span></a>matrices</p>
< <blockquote>
< <div><p>&lt;MappingProjection.matrix&gt;`.</p>
< </div></blockquote>
---
> it can be useful for custom configurations, including the implementation of specific Projection <a class="reference internal" href="MappingProjection.html#psyneulink.core.components.projections.pathway.mappingprojection.MappingProjection.matrix" title="psyneulink.core.components.projections.pathway.mappingprojection.MappingProjection.matrix"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">matrices</span></code></a>.</p>
550c547
< <span id="id3"></span><h2>Composition Structure<a class="headerlink" href="#composition-structure" title="Permalink to this headline">¶</a></h2>
---
> <span id="id1"></span><h2>Composition Structure<a class="headerlink" href="#composition-structure" title="Permalink to this headline">¶</a></h2>
626,628c623,625
< outer Composition, are assigned <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> in addition to their other <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole" title="psyneulink.core.compositions.composition.NodeRole"><code class="xref any py py-class docutils literal notranslate"><span class="pre">roles</span></code></a> in the
< nested Composition. The only difference between <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Nodes
< is whether their output is included in the <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> attributes of the <em>outermost</em> Composition to which they project; this is determined by the
---
> outer Composition, are assigned <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> in addition to their other <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole" title="psyneulink.core.compositions.composition.NodeRole"><code class="xref any py py-class docutils literal notranslate"><span class="pre">roles</span></code></a> in the
> nested Composition. The only difference between <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Nodes
> is whether their output is included in the <a class="reference internal" href="#id9" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> attributes of the <em>outermost</em> Composition to which they project; this is determined by the
631c628
< <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes are <em>not</em> included in the <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> or <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> for the outermost Composition to which they project (although they <em>are</em> still included
---
> <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes are <em>not</em> included in the <a class="reference internal" href="#id9" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> or <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> for the outermost Composition to which they project (although they <em>are</em> still included
635c632
< <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.include_probes_in_output" title="psyneulink.core.compositions.composition.Composition.include_probes_in_output"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">include_probes_in_output</span></code></a> is True, then any <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes
---
> <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.include_probes_in_output" title="psyneulink.core.compositions.composition.Composition.include_probes_in_output"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">include_probes_in_output</span></code></a> is True, then any <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes
637,638c634,635
< the <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> of the outermost Composition.
< <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes can be visualized, along with any Projections treated differently from those of
---
> the <a class="reference internal" href="#id9" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> of the outermost Composition.
> <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes can be visualized, along with any Projections treated differently from those of
646c643
< <div><p><a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes are useful for <a class="reference internal" href="OptimizationControlMechanism.html#optimizationcontrolmechanism-model-based"><span class="std std-ref">model-based optimization using an</span></a>, in which the value of one or more Nodes in a nested Composition
---
> <div><p><a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes are useful for <a class="reference internal" href="OptimizationControlMechanism.html#optimizationcontrolmechanism-model-based"><span class="std std-ref">model-based optimization using an</span></a>, in which the value of one or more Nodes in a nested Composition
666c663
< <p>A Node can be both a <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> and an <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Node of a nested Composition,
---
> <p>A Node can be both a <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> and an <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Node of a nested Composition,
670c667
< (those are treated in the same way as <a class="reference internal" href="#id27" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes).</p>
---
> (those are treated in the same way as <a class="reference internal" href="#id15" title="psyneulink.core.compositions.composition.NodeRole.PROBE"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">PROBE</span></code></a> Nodes).</p>
682c679
< both the <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> of the nested Composition
---
> both the <a class="reference internal" href="#id9" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">results</span></code></a> of the nested Composition
684c681
< <a class="reference internal" href="#id21" title="psyneulink.core.compositions.composition.Composition.output_values"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">output_values</span></code></a> and <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.results" title="psyneulink.core.compositions.composition.Composition.results"><code class
...

See CI logs for the full diff.

Copy link
Collaborator

@kmantel kmantel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good.

I'll try to fix the problems with build/html/Condition.html.

Did you notice these just looking through the warning messages on a build or did you see the missing table in the docs?

@jvesely
Copy link
Collaborator Author

jvesely commented May 1, 2024

Looks good.

I'll try to fix the problems with build/html/Condition.html.

Did you notice these just looking through the warning messages on a build or did you see the missing table in the docs?

Thank you.
I started looking at the warning stats from logs (grep 'WARNING: [^ ][^ ]* [^ ][^ ]*' -o docs/0_base.log | sort | uniq -c) and tried to fix a few low-count instances. (e.g. 3 WARNING: Malformed table.) Then I noticed the HTML diff and the fact that class="problematic" was removed so I focused on those.

I didn't find a way to selectively turn some warnings into errors to prevent reintroducing them later.
I think it'd be beneficial to gradually fix the warnings and enable the global switch, but there are still a lot of them.
In the meantime adding something like grep 'class="problematic"' check at the end of docs generation should help prevent introducing the most visible errors.

The current warnings count is:

$ grep "WARNING: [^ :][^ :]* *[^ :]* *[^ :]*" -o docs/9_subst.log  | sort | uniq -c
   1591 WARNING: 'any' reference target
      6 WARNING: autodoc
    112 WARNING: Block quote ends
    171 WARNING: Bullet list ends
     32 WARNING: Cannot resolve forward
      2 WARNING: circular toctree references
      5 WARNING: Content block expected
      3 WARNING: Could not obtain
     33 WARNING: Definition list ends
     19 WARNING: document isn't included
      3 WARNING: download file not
      9 WARNING: Duplicate explicit target
      1 WARNING: duplicate label acknowledgements,
      1 WARNING: duplicate label conventions,
      1 WARNING: duplicate label function_core_attributes,
      1 WARNING: duplicate label function_creation,
      1 WARNING: duplicate label function_execution,
      1 WARNING: duplicate label function_modulatory_params,
      1 WARNING: duplicate label function_overview,
      1 WARNING: duplicate label function_structure,
      1 WARNING: duplicate label help_and_issues,
      1 WARNING: duplicate label indices_and_tables,
      1 WARNING: duplicate label installation,
      1 WARNING: duplicate label overview,
      1 WARNING: duplicate label purpose,
      1 WARNING: duplicate label tutorial,
      1 WARNING: duplicate label what_psyneulink_is,
      1 WARNING: duplicate label what_psyneulink_is_not,
     62 WARNING: duplicate object description
    149 WARNING: Explicit markup ends
      2 WARNING: Field list ends
      1 WARNING: Figure caption must
      1 WARNING: image file not
     14 WARNING: Inline emphasis start-string
      6 WARNING: Inline strong start-string
      8 WARNING: Line block ends
      5 WARNING: Literal block ends
      1 WARNING: Literal block expected;
     15 WARNING: malformed hyperlink target.
      3 WARNING: missing attribute mentioned
   2861 WARNING: more than one
      4 WARNING: toctree contains reference
      1 WARNING: undefined label
      1 WARNING: Undefined substitution referenced
    157 WARNING: Unexpected indentation.
     11 WARNING: Unexpected section title.
      1 WARNING: Unknown interpreted text
     23 WARNING: unknown keyword

@jvesely jvesely merged commit 022c5b7 into PrincetonUniversity:devel May 1, 2024
34 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Documentation text
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants