Conf tree #22

oliver-sanders · 2020-04-29T10:34:17Z

Sibling PRs:

Highlights:

Autodocument Cylc/Parsec configurations from the new ConfigNode tree thing.
Add a powerful relative referencing syntax.

Examples:

This feature is configured using the options in :cylc:conf:`file.rc[foo][bar][baz]`:

.. cylc-scope: file.rc[foo][bar][baz]

(no need to specify the full path in this section because we have set the scope)

* :cylc:conf:`pub` - does something
* :cylc:conf:`aux` - does something else
* :cylc:conf:`foot` - and now for something completely different

.. cylc:scope::

(but we do have to remember to reset the scope afterwards)

Documentation:

All [auto-]documented in the cylc_lang extension, try building the docs 😀.

oliver-sanders · 2020-04-29T10:49:30Z

Tests failing due to dependency on cylc/cylc-flow#3559

oliver-sanders · 2020-04-29T10:55:55Z

cylc/sphinx_ext/cylc_lang/__init__.py

-
-   .. rst-example::
-
-      .. auto-cylc-conf:: my-conf2.rc


Can't auto-document from JSON any more.

datamel · 2020-05-01T16:32:08Z

cylc/sphinx_ext/cylc_lang/autodocumenters.py

+        types = {}
+        for obj in objects:
+            types.update(obj)
+        for name, info in sorted(types.items()):


Suggested change

for name, info in sorted(types.items()):

for _, info in sorted(types.items()):

My pylint is complaining about unused varible name - pycodestyle seems happy though! Happy to ignore.

datamel · 2020-05-01T16:34:02Z

cylc/sphinx_ext/cylc_lang/domains.py

@@ -195,59 +211,84 @@ def tokens_from_partials(partials):


 def tokens_relative(base, override):
-    """
+    """Return one pat h relative to the other.


typo

Suggested change

"""Return one pat h relative to the other.

"""Return one path relative to the other.

datamel · 2020-05-01T16:41:30Z

cylc/sphinx_ext/cylc_lang/domains.py

-    ret = {**base}
+    # ensure that base is an aboslute path
+    if not base.get('conf'):
+        return ValueError(f'{base} is not an absoute path')


Suggested change

return ValueError(f'{base} is not an absoute path')

return ValueError(f'{base} is not an absolute path')

datamel · 2020-05-01T16:42:14Z

cylc/sphinx_ext/cylc_lang/domains.py

    """
-    flag = False
-    ret = {**base}
+    # ensure that base is an aboslute path


Suggested change

# ensure that base is an aboslute path

# ensure that base is an absolute path

datamel · 2020-05-01T16:53:26Z

cylc/sphinx_ext/cylc_lang/domains.py

+# The following is a minimal domain for documenting parsec objects:
+
+def parsec_ref(tokens):
+    """The detokenise equivalent for parsec (much simpler).i


Suggested change

"""The detokenise equivalent for parsec (much simpler).i

"""The detokenise equivalent for parsec (much simpler).

Think this 'i' can go, unless I'm mistaken?

datamel · 2020-05-01T16:57:48Z

cylc/sphinx_ext/cylc_lang/domains.py

+        try:
+            docname = self.get(tokens)
+        except KeyError:
+            # object does not exist, "nitpicky" mode will pick this up


"nitpicky" mode - like that :)

datamel · 2020-05-01T17:01:44Z

cylc/sphinx_ext/cylc_lang/tests/test_autodocumenters.py

+
+
+def test_doc_section(simple_section):
+    """It should docuement configuration sections."""


Suggested change

"""It should docuement configuration sections."""

"""It should document configuration sections."""

datamel · 2020-05-01T17:06:34Z

So, I have started my review. Only a few typos from what I have read through so far. I still have to look at the sibling prs and double check some of the logic for my own sanity. Pytests are passing for me locally. I still have to look at the integration. Looks great so far!

* simplifies tokenisation which simplifies referencing.

datamel

I still need to test by building but I’ve read through code, only a few little things I’ve noticed so far.

cylc/sphinx_ext/cylc_lang/domains.py

datamel

I have built it, changes look great. Suggested changes to minor typos.

kinow

Tested with the cylc-doc PR.

oliver-sanders added this to the 1.0.1 milestone Apr 29, 2020

oliver-sanders self-assigned this Apr 29, 2020

This was referenced Apr 29, 2020

Conf tree cylc/cylc-doc#121

Merged

Conf tree cylc/cylc-flow#3559

Merged

oliver-sanders commented Apr 29, 2020

View reviewed changes

oliver-sanders requested a review from datamel April 29, 2020 14:42

oliver-sanders force-pushed the conf-tree branch from 06be747 to 6af90e8 Compare May 1, 2020 09:58

datamel reviewed May 1, 2020

View reviewed changes

oliver-sanders added 14 commits May 2, 2020 13:00

cylc_lang: document cylc/parsec specs and types

4ad57ae

.gitignore

5b66fe8

cylc_lang: handle user-defined configurations

3755551

cylc_lang: detokenise name for display

be3189b

remove debug

1380e45

cylc_lang: handle unset defaults

1111186

cylc_lang: tidy

229d7fb

cylc_lang: format default values nicely

7f1912c

cylc_lang: allow four levels of section nesting

6943dc6

cylc_lang: define default scope

89fd870

cylc_lang: permit trailing values

7d44c1f

cylc_lang: perfect relative referencing

6ad357b

cylc_lang: require configurations to have extensions

045ecd5

* simplifies tokenisation which simplifies referencing.

cylc_lang: prevent rst errors on empy string values

cd2c7ab

cylc_lang: format integer ranges nicely

548ac1b

oliver-sanders force-pushed the conf-tree branch from 6af90e8 to 548ac1b Compare May 2, 2020 12:01

datamel reviewed May 13, 2020

View reviewed changes

cylc/sphinx_ext/cylc_lang/domains.py Outdated Show resolved Hide resolved

address feedback

f386fa4

datamel approved these changes May 18, 2020

View reviewed changes

oliver-sanders requested a review from kinow May 18, 2020 15:03

kinow approved these changes May 19, 2020

View reviewed changes

kinow merged commit 1e91907 into cylc:master May 19, 2020

oliver-sanders deleted the conf-tree branch May 20, 2020 09:29

oliver-sanders modified the milestones: 1.0.1, 1.1.0 Jun 8, 2020

oliver-sanders mentioned this pull request Jun 8, 2020

cylc autodocumenter #12

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Conf tree #22

Conf tree #22

oliver-sanders commented Apr 29, 2020 •

edited

Loading

oliver-sanders commented Apr 29, 2020

oliver-sanders Apr 29, 2020

datamel May 1, 2020

datamel May 1, 2020

datamel May 1, 2020

datamel May 1, 2020

datamel May 1, 2020

datamel May 1, 2020

datamel May 1, 2020

datamel commented May 1, 2020

datamel left a comment

datamel left a comment

kinow left a comment

	for name, info in sorted(types.items()):
	for _, info in sorted(types.items()):

	"""Return one pat h relative to the other.
	"""Return one path relative to the other.

	return ValueError(f'{base} is not an absoute path')
	return ValueError(f'{base} is not an absolute path')

	# ensure that base is an aboslute path
	# ensure that base is an absolute path

	"""The detokenise equivalent for parsec (much simpler).i
	"""The detokenise equivalent for parsec (much simpler).



		def test_doc_section(simple_section):
		"""It should docuement configuration sections."""

	"""It should docuement configuration sections."""
	"""It should document configuration sections."""

Conf tree #22

Conf tree #22

Conversation

oliver-sanders commented Apr 29, 2020 • edited Loading

oliver-sanders commented Apr 29, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

datamel commented May 1, 2020

datamel left a comment

Choose a reason for hiding this comment

datamel left a comment

Choose a reason for hiding this comment

kinow left a comment

Choose a reason for hiding this comment

oliver-sanders commented Apr 29, 2020 •

edited

Loading