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

Add mention of "model_output_dir" key in documentation; fix broken crossrefs #188

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add mention of "model_output_dir" key in documentation; fix broken crossrefs #188

wants to merge 3 commits into from

Conversation

zkamvar
Copy link
Contributor

@zkamvar zkamvar commented Oct 2, 2024 •
edited
Loading

This adds a sidetone about "model_output_dir" in two places that mention model-output to fix #187

Requesting a review from @mmkerr because she's working on the manuscript and I want to make sure this is accurate.

Also requesting a review from @matthewcornell who requested the change and @annakrystalli who knows the most about this specification.

As a side note, I would have linked directly to the admin.json section in the sidenote, but Sphinx was deciding to be difficult about it:

Sphinx being annoying 
12:41:18 ~/path/to/hubDocs/docs
(znk/document-model-output/187)$ make html
Running Sphinx v7.1.2
[autosummary] generating autosummary for: coc/committee.md, coc/covenant.md, coc/enforcement-manual.md, index.md, overview/cite.md, overview/contact.md, overview/contribute.md, overview/data-storage.md, overview/definitions.md, overview/history.md, ..., user-guide/hub-structure.md, user-guide/intro-data-formats.md, user-guide/model-abstracts.md, user-guide/model-metadata.md, user-guide/model-output.md, user-guide/presentations.md, user-guide/sample-output-type.md, user-guide/software.md, user-guide/target-data.md, user-guide/tasks.md
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
myst v4.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'substitution', 'attrs_inline', 'deflist', 'amsmath', 'tasklist', 'colon_fence', 'dollarmath', 'fieldlist'}, 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={schema_version: ..., schema_branch: ...}, 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 33 source files that are out of date
updating environment: [new config] 33 added, 0 changed, 0 removed
reading sources... [100%] user-guide/tasks
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
                  copying downloadable files... [100%] files/202311-ecdc-hub-launch.pdf
copying static files... done
copying extra files... done
done
/path/to/hubverse-org/hubDocs/docs/source/quickstart-hub-admin/tasks-config.md:257: WARNING: Could not lex literal_block '{\n  "schema_version": "https://raw.githubusercontent.com/hubverse-org/schemas/main/v3.0.1/tasks-schema.json",\n  "rounds": [...],\n  "output_type_id_datatype": "character"\n}\n' as "json". Highlighting skipped.
/path/to/hubverse-org/hubDocs/docs/source/user-guide/hub-structure.md:10: WARNING: local id not found in doc 'user-guide/hub-config': 'hub-admin-config'
/path/to/hubverse-org/hubDocs/docs/source/user-guide/hub-structure.md:10: WARNING: local id not found in doc 'user-guide/hub-config': 'hub-admin-config'

====================== slowest reading durations =======================
0.066 user-guide/sample-output-type
0.055 user-guide/model-output
0.034 quickstart-hub-admin/tasks-config
0.024 user-guide/tasks
0.016 coc/covenant

Exception occurred:
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/docutils/nodes.py", line 741, in index
    return self.children.index(item, start, stop)
ValueError: <pending_xref: <inline...>> is not in list
The full traceback has been saved in /var/folders/9p/m996p3_55hjf1hc62552cqfr0000gr/T/sphinx-err-72_s488l.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Error 2

The error log is as follows. I'm not going to report it because I don't want to go through the process of creating a reproducible example of a sphinx site and I don't want to get yelled at for giving the maintainers a whole-ass repository.

# Platform:         darwin; (macOS-14.6.1-arm64-arm-64bit)
# Sphinx version:   7.1.2
# Python version:   3.10.14 (CPython)
# Docutils version: 0.19
# Jinja2 version:   3.1.2
# Pygments version: 2.15.1

# Last messages:
#   writing output... [ 73%]
#   user-guide/hub-structure
#   
#   
#   ====================== slowest reading durations =======================
#   0.066 user-guide/sample-output-type
#   0.055 user-guide/model-output
#   0.034 quickstart-hub-admin/tasks-config
#   0.024 user-guide/tasks
#   0.016 coc/covenant

# Loaded extensions:
#   sphinx.ext.mathjax (7.1.2)
#   alabaster (0.7.13)
#   sphinxcontrib.applehelp (1.0.4)
#   sphinxcontrib.devhelp (1.0.2)
#   sphinxcontrib.htmlhelp (2.0.1)
#   sphinxcontrib.serializinghtml (1.1.5)
#   sphinxcontrib.qthelp (1.0.3)
#   sphinx.ext.duration (7.1.2)
#   sphinx.ext.doctest (7.1.2)
#   sphinx.ext.autodoc.preserve_defaults (7.1.2)
#   sphinx.ext.autodoc.type_comment (7.1.2)
#   sphinx.ext.autodoc.typehints (7.1.2)
#   sphinx.ext.autodoc (7.1.2)
#   sphinx.ext.autosummary (7.1.2)
#   sphinx.ext.intersphinx (7.1.2)
#   myst_parser (4.0.0)
#   sphinx_design (0.6.0)
#   sphinxcontrib.mermaid (7.1.2)
#   sphinx_book_theme (unknown version)
#   pydata_sphinx_theme (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/cmd/build.py", line 290, in build_main
    app.build(args.force_all, args.filenames)
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/application.py", line 351, in build
    self.builder.build_update()
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 290, in build_update
    self.build(to_build,
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 360, in build
    self.write(docnames, list(updated_docnames), method)
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 567, in write
    self._write_serial(sorted(docnames))
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 574, in _write_serial
    doctree = self.env.get_and_resolve_doctree(docname, self)
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/environment/__init__.py", line 624, in get_and_resolve_doctree
    self.apply_post_transforms(doctree, docname)
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/environment/__init__.py", line 670, in apply_post_transforms
    transformer.apply_transforms()
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/transforms/__init__.py", line 80, in apply_transforms
    super().apply_transforms()
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/docutils/transforms/__init__.py", line 173, in apply_transforms
    transform.apply(**kwargs)
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/transforms/post_transforms/__init__.py", line 37, in apply
    self.run(**kwargs)
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/sphinx/transforms/post_transforms/__init__.py", line 115, in run
    node.replace_self(newnodes)
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/docutils/nodes.py", line 1007, in replace_self
    self.parent.replace(self, new)
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/docutils/nodes.py", line 980, in replace
    index = self.index(old)
  File "/path/to/hubverse-org/hubDocs/.venv/lib/python3.10/site-packages/docutils/nodes.py", line 741, in index
    return self.children.index(item, start, stop)
ValueError: <pending_xref: <inline...>> is not in list

matthewcornell
matthewcornell approved these changes Oct 2, 2024
View reviewed changes
Copy link

@matthewcornell matthewcornell left a comment

Choose a reason for hiding this comment

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

This looks good to me, though I'm not sure how to rigorously check the updated markdown links without a preview. Thanks!

@zkamvar
Copy link
Contributor Author

zkamvar commented Oct 2, 2024

This looks good to me, though I'm not sure how to rigorously check the updated markdown links without a preview. Thanks!

Luckily RTD checks the crosslinks automatically (they were broken earlier because I was not familiar with the system and assumed that it was always just screaming at me about something trivial).

The markdown preview is always going to be under the information from the checks in this repo. Here's the link: https://hubdocs--188.org.readthedocs.build/en/188/

mmkerr
mmkerr approved these changes Oct 3, 2024
View reviewed changes
Copy link
Contributor

@mmkerr mmkerr left a comment

Choose a reason for hiding this comment

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

Hi @Zhian, this looks good to me. I must admit I haven't gotten into this much detail in the manuscript, but this is good to know.

@annakrystalli
Copy link
Contributor

One very minor naming change requested for consistency throughout docs but overall looks great! Thanks @zkamvar !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@matthewcornell matthewcornell matthewcornell approved these changes

@mmkerr mmkerr mmkerr approved these changes

@annakrystalli annakrystalli Awaiting requested review from annakrystalli

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
hubverse Development overview
Status: No status
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

"model_output_dir" key not described in documentation
4 participants
@zkamvar @annakrystalli @matthewcornell @mmkerr