fix(docs): improve docs rendering #303
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Fixes #301: reject non-optional arguments after optional arguments Fixes #298: show default values for optional properties Fixes #302: omit "abstract" from interface properties (they are by definition abstract) Fixes #300: indicate optionals with "optional" instead of "or undefined" Fixes #299: render multiple jsdoc lines as multiple lines in sphinx
rix0rrr
approved these changes
Nov 8, 2018
| @@ -651,9 +651,14 @@ class SphinxDocsGenerator extends Generator { | |||
| this.code.line(); | |||
| } | |||
| const readonly = prop.immutable ? ' *(readonly)*' : ''; | |||
| const abs = prop.abstract ? ' *(abstract)*' : ''; | |||
| const abs = (parent.kind !== spec.TypeKind.Interface && prop.abstract) ? ' *(abstract)*' : ''; | |||
There was a problem hiding this comment.
I wonder about the value of showing "abstract" at all.
Does it help consumers of a class know that a method is abstract? Or do they simply care about what it would do if they were to call it?
There was a problem hiding this comment.
I think they do if they are looking to extend a class.
mergify bot
pushed a commit
that referenced
this pull request
Oct 3, 2022
…3 in /packages/@jsii/python-runtime (#3785) Updates the requirements on [cattrs](https://github.com/python-attrs/cattrs) to permit the latest version. <details> <summary>Changelog</summary> <p><em>Sourced from <a href="https://github.com/python-attrs/cattrs/blob/main/HISTORY.rst">cattrs's changelog</a>.</em></p> <blockquote> <h2>22.2.0 (2022-10-03)</h2> <ul> <li><em>Potentially breaking</em>: <code>cattrs.Converter</code> has been renamed to <code>cattrs.BaseConverter</code>, and <code>cattrs.GenConverter</code> to <code>cattrs.Converter</code>. The <code>GenConverter</code> name is still available for backwards compatibility, but is deprecated. If you were depending on functionality specific to the old <code>Converter</code>, change your import to <code>from cattrs import BaseConverter</code>.</li> <li><code>NewTypes <https://docs.python.org/3/library/typing.html#newtype></code>_ are now supported by the <code>cattrs.Converter</code>. (<code>[#255](python-attrs/cattrs#255) <https://github.com/python-attrs/cattrs/pull/255></code><em>, <code>[#94](python-attrs/cattrs#94) <https://github.com/python-attrs/cattrs/issues/94></code></em>, <code>[#297](python-attrs/cattrs#297) <https://github.com/python-attrs/cattrs/issues/297></code>_)</li> <li><code>cattrs.Converter</code> and <code>cattrs.BaseConverter</code> can now copy themselves using the <code>copy</code> method. (<code>[#284](python-attrs/cattrs#284) <https://github.com/python-attrs/cattrs/pull/284></code>_)</li> <li>Python 3.11 support.</li> <li>cattrs now supports un/structuring <code>kw_only</code> fields on attrs classes into/from dictionaries. (<code>[#247](python-attrs/cattrs#247) <https://github.com/python-attrs/cattrs/pull/247></code>_)</li> <li>PyPy support (and tests, using a minimal Hypothesis profile) restored. (<code>[#253](python-attrs/cattrs#253) <https://github.com/python-attrs/cattrs/issues/253></code>_)</li> <li>Fix propagating the <code>detailed_validation</code> flag to mapping and counter structuring generators.</li> <li>Fix <code>typing.Set</code> applying too broadly when used with the <code>GenConverter.unstruct_collection_overrides</code> parameter on Python versions below 3.9. Switch to <code>typing.AbstractSet</code> on those versions to restore the old behavior. (<code>[#264](python-attrs/cattrs#264) <https://github.com/python-attrs/cattrs/issues/264></code>_)</li> <li>Uncap the required Python version, to avoid problems detailed in <a href="https://iscinumpy.dev/post/bound-version-constraints/#pinning-the-python-version-is-special">https://iscinumpy.dev/post/bound-version-constraints/#pinning-the-python-version-is-special</a> (<code>[#275](python-attrs/cattrs#275) <https://github.com/python-attrs/cattrs/issues/275></code>_)</li> <li>Fix <code>Converter.register_structure_hook_factory</code> and <code>cattrs.gen.make_dict_unstructure_fn</code> type annotations. (<code>[#281](python-attrs/cattrs#281) <https://github.com/python-attrs/cattrs/issues/281></code>_)</li> <li>Expose all error classes in the <code>cattr.errors</code> namespace. Note that it is deprecated, just use <code>cattrs.errors</code>. (<code>[#252](python-attrs/cattrs#252) <https://github.com/python-attrs/cattrs/issues/252></code>_)</li> <li>Fix generating structuring functions for types with quotes in the name. (<code>[#291](python-attrs/cattrs#291) <https://github.com/python-attrs/cattrs/issues/291></code>_ <code>[#277](python-attrs/cattrs#277) <https://github.com/python-attrs/cattrs/issues/277></code>_)</li> <li>Fix usage of notes for the final version of <code>PEP 678 <https://peps.python.org/pep-0678/></code><em>, supported since <code>exceptiongroup>=1.0.0rc4</code>. (<code>[#303](python-attrs/cattrs#303) <303 <https://github.com/python-attrs/cattrs/pull/303></code></em>)</li> </ul> <h2>22.1.0 (2022-04-03)</h2> <ul> <li>cattrs now uses the CalVer versioning convention.</li> <li>cattrs now has a detailed validation mode, which is enabled by default. Learn more <code>here <https://cattrs.readthedocs.io/en/latest/validation.html></code>_. The old behavior can be restored by creating the converter with <code>detailed_validation=False</code>.</li> <li><code>attrs</code> and dataclass structuring is now ~25% faster.</li> <li>Fix an issue structuring bare <code>typing.List</code> s on Pythons lower than 3.9. (<code>[#209](python-attrs/cattrs#209) <https://github.com/python-attrs/cattrs/issues/209></code>_)</li> <li>Fix structuring of non-parametrized containers like <code>list/dict/...</code> on Pythons lower than 3.9. (<code>[#218](python-attrs/cattrs#218) <https://github.com/python-attrs/cattrs/issues/218></code>_)</li> <li>Fix structuring bare <code>typing.Tuple</code> on Pythons lower than 3.9. (<code>[#218](python-attrs/cattrs#218) <https://github.com/python-attrs/cattrs/issues/218></code>_)</li> <li>Fix a wrong <code>AttributeError</code> of an missing <code>__parameters__</code> attribute. This could happen when inheriting certain generic classes – for example <code>typing.*</code> classes are affected. (<code>[#217](python-attrs/cattrs#217) <https://github.com/python-attrs/cattrs/issues/217></code>_)</li> <li>Fix structuring of <code>enum.Enum</code> instances in <code>typing.Literal</code> types. (<code>[#231](python-attrs/cattrs#231) <https://github.com/python-attrs/cattrs/pull/231></code>_)</li> <li>Fix unstructuring all tuples - unannotated, variable-length, homogenous and heterogenous - to <code>list</code>. (<code>[#226](python-attrs/cattrs#226) <https://github.com/python-attrs/cattrs/issues/226></code>_)</li> <li>For <code>forbid_extra_keys</code> raise custom <code>ForbiddenExtraKeyError</code> instead of generic <code>Exception</code>. (<code>[#225](python-attrs/cattrs#225) <https://github.com/python-attrs/cattrs/pull/225></code>_)</li> <li>All preconf converters now support <code>loads</code> and <code>dumps</code> directly. See an example <code>here <https://cattrs.readthedocs.io/en/latest/preconf.html></code>_.</li> </ul> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/python-attrs/cattrs/commit/405f0291b958ae9eb45ee38febeb91fb65dd644f"><code>405f029</code></a> v22.2.0</li> <li><a href="https://github.com/python-attrs/cattrs/commit/89de04f57aa774d6abfb0ae62517dc8a8064e3c2"><code>89de04f</code></a> Fix some mor</li> <li><a href="https://github.com/python-attrs/cattrs/commit/0abbf271461babca203862f3581c20743f6118e0"><code>0abbf27</code></a> Fix tests</li> <li><a href="https://github.com/python-attrs/cattrs/commit/3b750439aec826a8fd20976ca113f30a27e75408"><code>3b75043</code></a> <strong>notes</strong> is list[str]</li> <li><a href="https://github.com/python-attrs/cattrs/commit/906b95cfef4903e2d6247abf0fdd72f7da21617a"><code>906b95c</code></a> Reorder HISTORY</li> <li><a href="https://github.com/python-attrs/cattrs/commit/ed7f86a0ccd9adeab895b9afac2dea69fa02bcff"><code>ed7f86a</code></a> Improve NewTypes (<a href="https://github-redirect.dependabot.com/python-attrs/cattrs/issues/310">#310</a>)</li> <li><a href="https://github.com/python-attrs/cattrs/commit/e7926599ad44e07d8325ae4072626e1a24705542"><code>e792659</code></a> Fix missing imports of preconf converters (<a href="https://github-redirect.dependabot.com/python-attrs/cattrs/issues/309">#309</a>)</li> <li><a href="https://github.com/python-attrs/cattrs/commit/e425d6378aa8dfc74bbdd9e152365e1b962fd8cf"><code>e425d63</code></a> Reorder HISTORY</li> <li><a href="https://github.com/python-attrs/cattrs/commit/cc56b2b873852a4e91b16706a39da00755c87759"><code>cc56b2b</code></a> Remove spurious type comment</li> <li><a href="https://github.com/python-attrs/cattrs/commit/cbd6f29d2c0ebc40805b3ca0d81accfc330eb10c"><code>cbd6f29</code></a> Reformat</li> <li>Additional commits viewable in <a href="https://github.com/python-attrs/cattrs/compare/v1.8.0...v22.2.0">compare view</a></li> </ul> </details> <br /> Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) </details>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #301: reject non-optional arguments after optional arguments
Fixes #298: show default values for optional properties
Fixes #302: omit "abstract" from interface properties (they are by definition abstract)
Fixes #300: indicate optionals with "optional" instead of "or undefined"
Fixes #299: render multiple jsdoc lines as multiple lines in sphinx
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.