Linting of doc/

[ns-rse]

Currently linting of Markdown documents in docs/ reports errors, these need fixing.

See also maxgamill-sheffield/btr_docs (or related branch) for where these were detected.

[MaxGamill-Sheffield]

My bad, this no longer seems to be a linting problem, more a Sphinx build problem as I can pass the pre-commit hooks now.
The output from the maxgamill-sheffield/btr-docs sphinx build is below:

(topo_test) Max:TopoStats Maxgamill$ sphinx-build -M html ./docs ./docs
Running Sphinx v7.4.7
loading translations [en]... done
loading pickled environment... done
[AutoAPI] Reading files... [100%] /Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/topostats/measure/geometry.py
WARNING: Cannot resolve import of unknown module topostats.measure.geometry in topostats.tracing.nodestats
WARNING: Cannot resolve import of unknown module topostats.measure.geometry in topostats.tracing.nodestats
WARNING: Cannot resolve import of unknown module topostats.measure.geometry in topostats.tracing.nodestats
[AutoAPI] Mapping Data... [100%] /Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/topostats/measure/geometry.py
[AutoAPI] Rendering Data... [  3%] geometry
[AutoAPI] Rendering Data... [  6%] topostats
[AutoAPI] Rendering Data... [ 10%] topostats.io
[AutoAPI] Rendering Data... [ 13%] topostats.logs
[AutoAPI] Rendering Data... [ 16%] topostats.theme
[AutoAPI] Rendering Data... [ 19%] topostats.scars
[AutoAPI] Rendering Data... [ 23%] topostats.utils
[AutoAPI] Rendering Data... [ 26%] topostats.grains
[AutoAPI] Rendering Data... [ 29%] topostats.filters
[AutoAPI] Rendering Data... [ 32%] topostats.tracing
[AutoAPI] Rendering Data... [ 35%] topostats._version
[AutoAPI] Rendering Data... [ 39%] topostats.plotting
[AutoAPI] Rendering Data... [ 42%] topostats.__main__
[AutoAPI] Rendering Data... [ 45%] topostats.logs.logs
[AutoAPI] Rendering Data... [ 48%] topostats.thresholds
[AutoAPI] Rendering Data... [ 52%] topostats.grainstats
[AutoAPI] Rendering Data... [ 55%] topostats.statistics
[AutoAPI] Rendering Data... [ 58%] topostats.processing
[AutoAPI] Rendering Data... [ 61%] topostats.validation
[AutoAPI] Rendering Data... [ 65%] topostats.entry_point
[AutoAPI] Rendering Data... [ 68%] topostats.run_topostats
[AutoAPI] Rendering Data... [ 71%] topostats.plottingfuncs
[AutoAPI] Rendering Data... [ 74%] topostats.tracing.pruning
[AutoAPI] Rendering Data... [ 77%] topostats.tracing.splining
[AutoAPI] Rendering Data... [ 81%] topostats.tracing.nodestats
[AutoAPI] Rendering Data... [ 84%] topostats.tracing.dnatracing
[AutoAPI] Rendering Data... [ 87%] topostats.tracing.skeletonize
[AutoAPI] Rendering Data... [ 90%] topostats.tracing.tracingfuncs
[AutoAPI] Rendering Data... [ 94%] topostats.tracing.dnacurvature
[AutoAPI] Rendering Data... [ 97%] topostats.tracing.ordered_tracing
[AutoAPI] Rendering Data... [100%] topostats.tracing.disordered_tracing

[autosummary] generating autosummary for: advanced/disordered_tracing.md, advanced/nodestats.md, advanced/ordered_tracing.md, advanced/splining.md, autoapi/geometry/index.rst, autoapi/index.rst, autoapi/topostats/__main__/index.rst, autoapi/topostats/_version/index.rst, autoapi/topostats/entry_point/index.rst, autoapi/topostats/filters/index.rst, ..., html/_static/scripts/bootstrap.js.LICENSE.txt, html/_static/vendor/fontawesome/6.5.2/LICENSE.txt, html/_static/vendor/fontawesome/6.5.2/js/all.min.js.LICENSE.txt, index.rst, installation.md, introduction.md, notebooks.md, related_software.md, usage.md, workflow.md
myst v4.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 32 source files that are out of date
updating environment: 0 added, 37 changed, 0 removed
[AutoAPI] Adding AutoAPI TOCTree [autoapi/index] to index.rst

/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/geometry/index.rst:137: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/geometry/index.rst:141: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/geometry/index.rst:144: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/geometry/index.rst:191: ERROR: Unexpected indentation.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/geometry/index.rst:186: WARNING: Inline literal start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/geometry/index.rst:186: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/geometry/index.rst:193: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/geometry/index.rst:193: WARNING: Inline literal start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/geometry/index.rst:193: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/grains/index.rst:148: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/grains/index.rst:245: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/grains/index.rst:277: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/grains/index.rst:339: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/grains/index.rst:371: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/plotting/index.rst:427: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/thresholds/index.rst:117: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/thresholds/index.rst:152: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/thresholds/index.rst:187: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/thresholds/index.rst:222: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/thresholds/index.rst:257: WARNING: Inline strong start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:317: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:313: ERROR: Unexpected indentation.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:310: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:314: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:314: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:314: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:314: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:323: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:323: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:326: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:327: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:327: WARNING: Inline substitution_reference start-string without end-string.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:944: ERROR: Undefined substitution referenced: "a".
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:944: ERROR: Undefined substitution referenced: "b".
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:944: ERROR: Undefined substitution referenced: "a||b".
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:42: ERROR: Unknown target name: "np.bool".
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:649: ERROR: Unknown target name: "np.bool".
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:729: ERROR: Unknown target name: "np.bool".
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/nodestats/index.rst:781: ERROR: Unknown target name: "np.bool".
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/skeletonize/index.rst:447: WARNING: Enumerated list ends without a blank line; unexpected unindent.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/skeletonize/index.rst:482: WARNING: Enumerated list ends without a blank line; unexpected unindent.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/tracing/skeletonize/index.rst:679: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/autoapi/topostats/utils/index.rst:227: WARNING: Inline strong start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/html/_static/scripts/bootstrap.js.LICENSE.txt: WARNING: document isn't included in any toctree
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/html/_static/vendor/fontawesome/6.5.2/LICENSE.txt: WARNING: document isn't included in any toctree
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/html/_static/vendor/fontawesome/6.5.2/js/all.min.js.LICENSE.txt: WARNING: document isn't included in any toctree
done
preparing documents... done
copying assets... 
copying static files... done
copying extra files... done
copying assets: done
writing output... [100%] index
/Users/Maxgamill/Desktop/Uni/PhD/topo_test/TopoStats/docs/advanced/ordered_tracing.md:86: WARNING: 'myst' cross-reference target not found: 'LINK'
generating indices... genindex py-modindex done
highlighting module code... [100%] topostats.validation
writing additional pages... search done
copying images... [100%] _static/images/splining/topostats_file.png
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 50 warnings.

The HTML pages are in docs/html.
(topo_test) Max:TopoStats Maxgamill$ 

Are these essential to fix for the release @ns-rse? Some of the nodestats complaints seem to surround how I've structured the dictionary returns, or equation labels i.e:

[MaxGamill-Sheffield]

How the above dict looks in the docs:

[ns-rse]

It looks like an image has been substituted in favour of inline code showing the dictionary structure.

All other linting issues appear to have been resolved so I'm closing.

[ns-rse]

My mistake, I only looked at the advanced/nodestats.md rendering. On closer inspection it looks like @MaxGamill-Sheffield question is about how to structure the docstring and its subsequent rendering. That is a Restructured Text markup issue and the documentation on how to here (this thread might be useful too).

[ns-rse]

These still persist...

Perhaps try around with the .. code-block:: construct, may be useful to ditch the | -> and put it in YAML format as you can then specify the language and it will apply syntax highlighting automatically courtesy of the pygments package if I've understood the documentation correctly.