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

Missing bound argument for TypeVar in output #8924

Closed
jp-larose opened this issue Feb 23, 2021 · 0 comments
Closed

Missing bound argument for TypeVar in output #8924

jp-larose opened this issue Feb 23, 2021 · 0 comments
Labels
extensions:autodoc type:enhancement enhance or introduce a new feature
Milestone
4.0.0

Comments

@jp-larose
Copy link

Describe the bug
When documenting a typing.TypeVar where the bound argument is specified, I would expect the generated document to show that information.

To Reproduce

$ git clone https://gitlab.com/joel.larose/sphinx_jpl.git
$ cd sphinx_jpl
$ pip install sphinx
$ make html

Compare typevar_example.py to build/html/modules/typevar_example.html
Notice that TypeE and TypeF are both defined with the bound argument, but it does not appear in the final document output.

Expected behaviour
Final output should include the bound argument when producing the output for a TypeVar
e.g.

TypeE = TypeVar('TypeE', bound=A)
"""This type variable is bound by class `A`"""

Should produce something like:

TypeE

This type variable is bound by class A
alias of TypeVar(‘TypeE’, bound=A)

Your project
https://gitlab.com/joel.larose/sphinx_jpl

Environment info

  • OS: Win10
  • Python version: 3.9
  • Sphinx version: 3.5.1
  • Sphinx extensions: sphinx.ext.autodoc, sphinx.ext.autosummary

Additional context
A patch to fix the output for the other arguments of TypeVar was completed in #8471
I suspect the fix for this would be very similar.
@tk0miya tk0miya added extensions:autodoc type:enhancement enhance or introduce a new feature and removed type:bug labels Feb 24, 2021
@tk0miya tk0miya added this to the 4.0.0 milestone Feb 24, 2021
tk0miya added a commit to tk0miya/sphinx that referenced this issue Feb 24, 2021
@tk0miya
Close sphinx-doc#8924: autodoc: Support bound argument for TypeVar
a39cf57
@tk0miya tk0miya mentioned this issue Feb 24, 2021
Merged
tk0miya added a commit that referenced this issue Feb 25, 2021
@tk0miya
Merge pull request #8927 from tk0miya/8924_TypeVar_bound
6d91db3 
Close #8924: autodoc: Support `bound` argument for TypeVar
@tk0miya tk0miya closed this as completed Feb 25, 2021
KunKaxx pushed a commit to KunKaxx/sphinx that referenced this issue Mar 11, 2021
@tk0miya @Blendify
@pradyunsg @jdufresne @francoisfreitag @Mardelor @bosonogi @farisachugthai @jfbu @stevepiercy @DelazJ @mcmtroffaes @graingert @jakobandersen @jantonguirao @askhl @larsoner @igo95862 @naveen521kk
Master.patch (#1)
3134085 
* Fix missing module: warnings

* Update CHANGES for PR sphinx-doc#8070

* Makefiles: Include clean in help message

The make clean help command was missing from all make files.

* Update make.bat_t

* Update Makefile_t

* Reword section on Third Party Themes

- No longer attempt to be the location for listing themes -- only Sphinx-RTD-Theme was listed here.
- Mention the classifier used when searching on PyPI.
- Emphasize sphinx-themes.org as a gallery of themes.

* Fix mypy violations

* Fix sphinx-doc#8342: Emit a warning if a unknown domain is given for directive or role

Currently, Sphinx mention nothing if users use unknown domain in their
documents (ex. `.. unknown:directive::`, `:unknown:role` and so on).
This starts to warn them to be clear non acceptable mark-ups.

refs: sphinx-doc#8342

* Close sphinx-doc#7996: manpage: Make a section directory on build manpage by default

* Test and document support for Python 3.9 release

* Drop code for supporting py35

* Remove additional mentions of Python 3.5

* Fix flake8 issue

* Fix sphinx-doc#8380: html search: search results are wrapped with <p> instead of <div>

* Drop code for py35

* Do test with Ubuntu 18.04

Sphinx-4.0 will drop support for Ubuntu 16.04.  So CI Platform should be
also updated to Ubuntu 18.04.

* Do isort

* Fix flake8 violation

* Remove config variable: source_parsers

It was already deprecated at 1.8.0 and removed at 3.0.0.  So the
definition is no longer used.

refs: dc45877

* Fix flake8 violations

* Remove code for python3.5

* Fix importing error

* Fix flake8 warnings

* Change html_logo & favicon config value process to handle url as values

* Fix sphinx-doc#8508: LaTeX: uplatex becomes a default setting of latex_engine for Japanese

Since v2.3, Sphinx supports uplatex as an alternative of latex_engine for Japanese
docs (refs: sphinx-doc#4186, sphinx-doc#6841). uplatex is able to build a document without conversion
character encoding internally. It allows using unicode characters in documents.
Additionally, uplatex is compatible with platex (current default latex_engine for
Japanese docs).

This changes the default latex_engine for Japanese document to uplatex.

* Fix basic layout and html_logo & favicon config value process to support url as values

* Update layouts to reference logo & favicon without static

* Fix style check errors

* Prevent page brake in the middle of a `seealso` 

* Fold long line

* Fix a flake8 violation

* Remove deprecated function: sphinx.ext.autodoc.importer:_getmro()

* Update the sphinx core events in appappi.rst

I'm very happy to see that the events in Sphinx have been laid out in order as they have been in this doc.

With that being said the notation I noticed was a bit odd. Some of the items in the list refer to events and as a result,
parenthesis are used to indicate the beginning and end of the parameters that the event takes.

In other items in the list, parenthesis are used for additional context for an event. The combination of some particularly very long lines,
the intermixing of comments, pseudo-code, indentation of items following a `for` or an `if` made this very difficult to read on a mobile device.

As a result, I've added whitespace, fixed a typo, reduced the length of some lines by moving them to a new line, and removed all `()` that were not
present to indicate parameters fed to a function.

* Fix mypy violations

* test: py domain: Add a testcase for :var: field

* Close sphinx-doc#5977: :var: field do not create a cross-reference

Since its beginning, `:var:` field has created a cross-reference to the
attribute having the same name.  It is meaningful only if the attribute
is documented by `py:attribute` directive.  It means the `:var:` field
and `:attr:` role are almost the same and conflicted.  Additionally,
the cross-reference points incorrect variable if the target is not
documented.

Thus, the cross-reference feature of `:var:` field is disabled.

* refactor: Move CSS tags in basic/layout.html to ``css_files`` variable

To make CSS customizable, all CSS files in basic/layout.html has their
priority: 200.  Therefore, extensions and users can insert their own
custom CSS files before or just after them.

As a side effect, the CSS tags in basic/layout.html are removed.  These
CSS files will be rendered via `css_files` template variable.

refs: sphinx-doc#8634, c5f0398

* refactor: Do not import sphinx.util.smartypants because of deprecated

* Fix sphinx-doc#4550: The align attribute of figure nodes becomes None by default

To keep compatibility with the standard doctree model of docutils,
this stops to use 'default' value as a default value of the align
attribute for figure and table nodes.

* refactor: test: Do not use deprecated function: execfile_()

* Close sphinx-doc#5560: napoleon_use_param also affect "other parameters" section

* LaTeX: update default font configuration

This replaces times package with tgtermes and tgheros (clones of Times and
Helvetica with better LaTeX support) and the monospace font from txfonts
package (txtt). This font is better matched with Times-like fonts than
Courier clones.

The changes applies to pdflatex/platex/uplatex.

Fixes: sphinx-doc#8711

* pour tester token

	new file:   dummy

* test

* test

* Cleaning up accidental mess

My apologies.  I was testing authentication token, pushing master to my
forked repo.  But I ended up accidentally pushing to sphinx-doc/sphinx,
and force pushing afterwards to clean up then was rejected.

	deleted:    dummy

* refactor: html theme: Insert documentation_options.js via script_files

* refactor: Index class becomes subclasses of abc.ABC

The `Index` class becomes subclasses of `abc.ABC` to indicate
methods that must be overrided in the concrete classes.

* Update the link to the new sphinx-contrib organization

This should be backported to at least 3.x, too.

* refactor: Add sphinx.util:isurl()

* html theme: Add `favicon_url` and `logo_url`

To embed the external favicon and logo image, this adds new template
variable `favicon_url` and `logo_url` that point the external URL or
relative path for the favicon/logo file from current file.  It helps to
use it on template files.

* Update CHANGES

* doc: html_favicon and html_logo accept URL now

* Update CHANGES for PR sphinx-doc#8510

* refactor: Remove unused method

* Fix sphinx-doc#6550: Emit a deprecation warning for html_add_permalinks

Let's start to emit a deprecation warning for html_add_permalinks since
the major release v4.0.

* Fix sphinx-doc#8737: html: broken img tag is appeared when html_logo not set

* LaTeX: sync pdftex engine default imageresolution with pxunit

Closes: sphinx-doc#8253

The 'pxunit' key from latex_elements instructs how to handle image
dimensions specified in px units.

But pdftex has \pdfimageresolution which is used when an image file does
not provide readable or legit values for the x and/or y resolution.

This commit syncs them: from 'pxunit' the default image resolution in
pixels per inch (an integer) is computed.

This way an image will behave the same if:

- it is loaded with no explicit size set, _and_ no readable image
  resolution data is readable from the file (or that data matches the
  'pxunit' setting)

- or a size is set in figure directive using px units and equal to the
  natural pixel size of the image,

This also with 'lualatex' but is ignored by with 'xelatex' and
'uplatex'.

* html: html_codeblock_linenos_style defaults to 'inline' (refs: sphinx-doc#7849)

As discussed in sphinx-doc#7879, the default style of line numbers for code
blocks in HTML output becames 'inline' by default.  And 'table' style
is now deprecated and will be removed in Sphinx-6.0.

* Refactor LaTeX [1/2]: split sphinx.sty into separate components

The latex macros from sphinx.sty were already partitioned into
successive sections.  The file sphinx.sty is split into multiple
files in concordance with this pre-existing sectioning.

The files are loaded via \input. File extension is .sty not .tex
to not confuse the Makefile.

* Refactor LaTeX [2/2]: renamings of auxiliary Sphinx LaTeX packages

sphinxcyrillic -> sphinxpackagecyrillic
sphinxmulticell -> sphinxpackagemulticell
footnotehyper-sphinx -> sphinxpackagefootnote

* Update CHANGES for PR sphinx-doc#8769

* Refactor LaTeX [3/2]: Add all missing .sty in the \ProvidesFile

Sorry for oversight

* Refactor LaTeX [4/2]: suppress extra bracket from bad latex merge :(

* Revert alteration at c9480f9 merge of 3.x of doc/conf.py

Compare doc/conf.py after merge at c9480f9 to what it was at 2ee0338.

It loses the modification from sphinx-doc#8716 (merged at 38c6143) and thus
reverts doc/conf.py to former font config using mathpazo.

* Refactor LaTeX style files

This is a (continuation and) re-work of sphinx-doc#8769 (e6bf914)

I have reintegrated option handling and most package loading into the
original file sphinx.sty and reorganized completely the filenames of
secondary style files.

sphinx.sty had become too big and first sphinx-doc#8769 now this more definitive
refactoring is necessary to clarify structure, dependencies, and ease up
future maintenance.

Unfortunately this means a lot of moving around hunks of latex code with
some alterations.  I tried to carefully check everything is defined in
right order (as LaTeX being a macro expansion language, often one can
manipulate things before them being defined, nevertheless I checked
things are done in order).

Only simple thing is to review is that I added missing EOLs at last
lines of the extracted files...

* Fix markup in docs (from d6e11b8)

* LaTeX: document what the style files provide and require

* Fix accidental revert of f937fac (sphinx-doc#8767) by sphinx-doc#8790 merge

Due to file renaming

* Fix lost LaTeX in merge

* Re-insert if isinstance(node, ast.Constant): into py _parse_annotation

As master drop python 3.5 support, conditional

    if sys.version_info >= (3, 6):

not needed anymore.  This hunk had got lost in merge.

	modified:   sphinx/domains/python.py

* refactor: py domain: Put if-block for ast.Constant to the root level

* Make code block types more visible

* Update type annotations

* Update latex comment

* fix potential getitem error in resolve_anyref

* refactor: Remove meaningless type annotations

* migrate html_add_permalinks=None and html_add_permalinks=""

The docs list: Set it to None or the empty string to disable permalinks.

* C++, cpp_index_common_prefix remove longest

Fixes sphinx-doc#8911

* Fix sphinx-doc#8915: html theme: The translation of sphinx_rtd_theme does not work

Since sphinx_rtd_theme-0.5.0, it supports translations.  But Sphinx core
disallows to enable it because theming framework gives special treatment
for the theme for a long time.

This goes to load it via setuptools at first to enable the translations.

Note: The special treatment for sphinx_rtd_theme (< 0.2.5) is not
removed yet.  But it will be removed in the future release.

* Close sphinx-doc#8924: autodoc: Support `bound` argument for TypeVar

* C, properly error on keywords as function parameters

* C, remove dead code

* C, remove more dead code

* C, simplify tests

* C, test namespace revamp

* LaTeX: let underfull calculation in wrapped code lines ignore last line

Closes: sphinx-doc#8925

* Update CHANGES

* Gather LaTeX items in CHANGES for 4.0.0

* Fix sphinx-doc#8917: autodoc: Raises a warning if function has wrong __globals__ value

`sphinx.util.inspect:signature()` crashes with AttributeError when
subject has wrong `__globals__` value.  This ignores the error on
building.

* Fix sphinx-doc#8933: viewcode: Failed to create back-links on parallel build

On parallel build mode, viewcode losts the back-links information on
gathering results from each process.  As a result, some back-links are
missing in the generated viewcode pages.

This fixes the merging back-links process for parallel builds.

* refactor: LaTeX: Use raw strings for LaTeX macros

* Use explicit title for titlenode, when no title is provided

Signed-off-by: Joaquin Anton <janton@nvidia.com>

* Fix sphinx-doc#8938: imgconverter: Show the error of the command availability check

imgconverter extension suppresses an OSError like "Cannot allocate
memory" unexpectedly.  So the error should be shown with the warning.

* autodoc: an imported TypeVar is not resolved (refs: sphinx-doc#8415)

So far, a TypeVar is rendered without module name. As a result, it
could not be resolved if it is imported from other modules.  This
prepends its module name and make it resolvable.  This is available
only in Python 3.7 or above.

As a side effect, all of TypeVars are displayed with module name. It
should be fixed in latter step (refs: sphinx-doc#7119)

* Close sphinx-doc#8326: Rename master_doc to root_doc

To describe the purpose more accurately, the `master_doc` is now renamed
to `root_doc`.  The old name is still available.  But it is recommeneded
to use new one from now on.

* Update sphinx/builders/html/__init__.py

* Update sphinx/builders/html/__init__.py

* Update CHANGES for PR sphinx-doc#8905

* Apply code review suggestions

Signed-off-by: Joaquin Anton <janton@nvidia.com>

* Deprecate SphinxComponentRegistry.get_source_input()

The source_input system was deprecated at v2.0.  So no client uses it
longer now.  Therefore this deprecate the getter interface and its
usage.

* Update CHANGES for PR sphinx-doc#8937

* C++, support spaceship operator

Fixes sphinx-doc#8942

* format translatable strings in one go.  This enables translation tools like msgfmt to verify that an incorrect translation cannot crash sphinx-build.  This will fix current crashes for Hungarian and Greek (Spanish was fixed in sphinx-doc#8941)

* BUG: Fix rebuild regression

* C and C++, fix nested paramter lists

* Fix py.typed file not being included in source archive

* Add pending_xref_condition node

To choose appropriate content for pending_xref node on resolving,
this introduces a new custom node `pending_xref_condition`.  It only
has a condition for the filtering and contents of the reference.

* Filter pending_xref_condition node on failed resolution

* Fix sphinx-doc#7199: py domain: Add a new confval: python_use_unqualified_type_names

Add a new config variable: python_use_unqualified_type_names.  If enabled,
it goes to suppress the module name of the python reference if it can be
resolved.

* intersphinx: Support pending_xref_condition

* Fix sphinx-doc#759: autodoc: Add sphinx.ext.autodoc.preserve_defaults extension

Add a new extension `sphinx.ext.autodoc.preserve_defaults`.

It preserves the default argument values of function signatures in source code
and keep them not evaluated for readability.  This is an experimental
extension and it will be integrated into autodoc core in Sphinx-4.0.

* doc: Update document for autodoc :members: option

* doc: Update document for autodoc :undoc-members: option

* doc: Update document for autodoc :private-members: option

* doc: Update document for autodoc :special-members: option

* doc: Fix indentation

* Fix wrong directive name in warning messages

* Sphinx is available on Chocolatey

* lint

* Close sphinx-doc#8487: csv-table now considers abspath as relpath from srcdir

To make directives' behavior consistent, the :file: option for
csv-table directive now recognizes an absolute path as a relative
path from source directory.

* doc: Create autodoc extension tutorial

* doc: Added autodoc extension tutorial to tutorials index

* doc: Link autodoc tutorial in add_autodocumenter docstring

Uses :ref: link because :doc: does not work.

* doc: Added reflink to autodoc tutorial

Used in add_autodocumenter docstring

* Close sphinx-doc#7549: autosummary: Enable autosummary_generate by default

Co-authored-by: Takeshi KOMIYA <i.tkomiya@gmail.com>
Co-authored-by: Aaron Carlisle <carlisle.b3d@gmail.com>
Co-authored-by: Aaron Carlisle <carlisle.aaron00@gmail.com>
Co-authored-by: Pradyun Gedam <3275593+pradyunsg@users.noreply.github.com>
Co-authored-by: Jon Dufresne <jon.dufresne@gmail.com>
Co-authored-by: François Freitag <mail@franek.fr>
Co-authored-by: Mardelor <remy.zirnheld@laposte.net>
Co-authored-by: Toni Ruža <toni.ruza@gmail.com>
Co-authored-by: Faris A Chugthai <20028782+farisachugthai@users.noreply.github.com>
Co-authored-by: jfbu <jfbu@free.fr>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Harrissou Sant-anna <delazj@gmail.com>
Co-authored-by: Matthias C. M. Troffaes <matthias.troffaes@gmail.com>
Co-authored-by: Thomas Grainger <tagrain@gmail.com>
Co-authored-by: Jakob Lykke Andersen <Jakob@caput.dk>
Co-authored-by: Jakob Lykke Andersen <jakobandersen@users.noreply.github.com>
Co-authored-by: Joaquin Anton <janton@nvidia.com>
Co-authored-by: Ask Hjorth Larsen <asklarsen@gmail.com>
Co-authored-by: Eric Larson <larson.eric.d@gmail.com>
Co-authored-by: igo95862 <igo95862@yandex.ru>
Co-authored-by: Naveen M K <naveen@syrusdark.website>
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 13, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
extensions:autodoc type:enhancement enhance or introduce a new feature
Projects
None yet
Milestone
4.0.0
Development

No branches or pull requests
2 participants
@tk0miya @jp-larose