Incorrect predictions when fitting a LogisticRegression model on binary outcomes with . Incorrect predictions when fitting a LogisticRegression model on binary outcomes with . <!-- Example: Joblib Error thrown when calling fit on LatentDirichletAllocation with evaluateevery 0--<!-- Example: If the code is too long, feel free to put it in a public gist and link it in the issue: --If we compare against R or using , the log loss (which is approximately proportional to the objective function as the regularisation is set to be negligible through the choice of ) is incorrect. We expect the log loss to be roughly The actual log loss when using is . See the stack exchange question for more information. The issue it seems is caused in In the case even if we cannot reduce to a 1D case by throwing away one of the vectors of coefficients (as we can in normal binary logistic regression). This is essentially a difference between softmax (redundancy allowed) and logistic regression. This can be fixed by commenting out the lines 762 and 763. I am apprehensive however that this may cause some other unknown issues which is why I am positing as a bug. <!-- Please run the following snippet and paste the output below. import platform; print(platform.platform()) import sys; print("Python", sys.version) import numpy; print("NumPy", numpy.version) import scipy; print("SciPy", scipy.version) import sklearn; print("Scikit-Learn", sklearn.version) --Linux-4.10.0-33-generic-x8664-with-Ubuntu-16.04-xenial Python 3.5.2 (default, Nov 17 2016, 17:05:23) NumPy 1.13.1 SciPy 0.19.1 Scikit-Learn 0.19.0 <!-- Thanks for contributing! --


autodocunqualifiedtypehints does not work well with autodoctypehints="description" autodocunqualifiedtypehints does not work well with autodoctypehints="description". Typehints in info-field-list are also changed to the short style when autodocunqualifedtypehints enabled. N/A No response Mac 10.1 HEAD of 4.x autodoc No response No response


Change "Permalink to this headline" to use "heading" instead Sphinx-generated tooltips for headings use "Headline" instead of "Heading". Picking out of Build any Sphinx documentation, containing one or more headings (eg: ). When hovering over the Sphinx-injected "headerlink", notice that it says "Headline" instead of "Heading". Instead of: Permalink to this headline The tooltip should be: Permalink to this heading <img width="235" alt="Screenshot 2022-01-01 at 17 20 09" src="https://user-"N/A N/A No response No response The relevant chunk of code: This will also need some update to the translated strings, which means that this will likely need to be a Sphinx 5.0+ change?


Latex: long option name overflows in Index Let's consider something like: Leads to the following with . ! Build snippet. No response Build the snippet No response Linux 8 0 No response No response No response


Allow to bail out extlink replacement suggestion Feature via Consider the following ext link: and the following text: ` Can we somehow bailout out the check here, or perhaps the suggestion should only apply if there's no in the extlink, what do you think? cc


Alternating multiply referred footnotes produce a ? in pdf output In some circumstances footnote mark is rendered as and there is no hyperlink file : then . Footnotes are rendered correctly See above code ! Mac 7 (CPython) 0 and current 4.x (v4.5.0+/) No response No response No response


Overridden, overloaded class docstring return type rendered as None Some overloaded class definitions show ` as a return type, when there shouldn't be any return type. This seems to happen when the overloaded functions are overridden in the final docstring. A class without this problem is also provided for comparison. Exactly the same as ! ! Ubuntu 3 0 '', '', 'sphinxrtdtheme' No response Related Sphinx issue: This was originally reported in


autodocpreservedefaults=True does not work for mixture of keyword only arguments with/without defaults If I understand correctly, the following is a valid signature of a class method: When documenting this with autodoc and , generates a with for the arguments. This later raises an exception in since the dunder method now returns instead of a string. Basically what happens is that ast generates a value in the of the since the first keyword argument is required, but simply ignores that argument because the is empty. This leaves the in the to be picked up when the keyword argument with default value is processed -- instead of the actual default. This can't be resolved by the call which therefore simply returns , which ends up as the of the . Imo this could simply be resolved by ing the corresponding from the if a parameter with empty is encountered. Create a module with contents and auto-document while setting in your Make sure sphinx tries to document all parameters, (since it's a method, they will be documented when the autodoc directive has , if you try the same with a module level method you need to document the parameters) The correct default value should be documented. The Warning Message also is pretty worthless (probably the value should not be formatted with a simple but instead with a ?) Any Tested with versions 3.8 0


Use of literalinclude prepend results in incorrect indent formatting for code eamples Cannot determine a mechanism to use literalinclude directive with or to match code example indentation, as leading whitespace is removed. Example of including xml snippet, that should be prefixed with . File: File : Produces the following valid xml, which is indented poorly: I cannot think of good warning free way to indent to match the included code example. Expect leading white space to be preserved in output: No response Mac 10 0 ['', ''] No response Using creatively almost provides a workaround: Produces a warning, which fails the build with build policy. Use of could be a good solution, if was applied only to the literalinclude and not to the and content.


inherited-members should support more than one class Is your feature request related to a problem? Please describe. I have two situations: A class inherits from multiple other classes. I want to document members from some of the base classes but ignore some of the base classes A module contains several class definitions that inherit from different classes that should all be ignored (e.g., classes that inherit from list or set or tuple). I want to ignore members from list, set, and tuple while documenting all other inherited members in classes in the module. Describe the solution you'd like The :inherited-members: option to automodule should accept a list of classes. If any of these classes are encountered as base classes when instantiating autoclass documentation, they should be ignored. Describe alternatives you've considered The alternative is to not use automodule, but instead manually enumerate several autoclass blocks for a module. This only addresses the second bullet in the problem description and not the first. It is also tedious for modules containing many class definitions.


Reference targets not found when using When using the above directive in my for sphinx, I suddenly get the following output: Previously I had , but when changing this behaviour suddenly it cannot find these names/targets. NOTE: I use the following command to generate my docs, hence being able to see all warnings as errors:- I expected the docs to build correctly with the resolved types and reference links. N/A I think ! Linux - Debian 10 6 0 , , , , sphinxcontribtrio, resourcelinks No response No response


doesn't work on class methods Default values for class methods are rendered as their , even with in Extract the and run . Note that the default value for the argument of the regular and static methods render correctly as , but the default value for the class method renders as its repr. All three methods' argument's default values should render as Screenshot of the rendered attached example demonstrating incorrect rendering: ! Arch Linux 10.0 Tested on 4.5 and current 5.x branch (commit ) No response No response


LaTeX: new Inline code highlighting from adds whitespace at start and end in pdf output The enhancement activates syntax highlighting for the Docutiles role. For LaTeX output, a space character is inserted at start and end of the inline code. Example a priori, mark-up should be: But I have no no strong opinion if good or bad. See screenshots. in and . No response extracted from with current: ! if space characters removed from file produced by LaTeX writer: ! For comparison prior to merge: ! Mac 9 No response No response Relates


causes autoclass to put a return type Using the option causes Sphinx's to include the class's "return type" for code such as this: <details<summaryOld repro, the repository no longer exists</summary</detailsa folder. that folder create files: : : : a virtual environment and install Sphinx 4.4 in it. into the docs folder and build the documentation with a command (in activated virtual environment): in the browser and see the issue. I expected there to be no return type listed for the class. Here's a link to generated docs: https://sphinx-issue- Windows 10, Ubuntu 18.04 7, 3.8, 3.9 0 No response No response


Fix duplicated args and kwargs with autodoctypehints Fix duplicated args and kwargs with autodoctypehints Bugfix Consider this when using the autodoc extension and the setting . WIth sphinx 4.2.0, the current output is where the args and *kwargs are duplicated and incomplete. The expected output is


fails to remove more than one meta-field from a fieldlist If a field list contains more then one "meta"-field, the generated documentation shows all but the first meta-field. It is a classical coding bug: the function stops removing meta fields after the first meta-field. Generated documentation contains a box with the text . The generated documentation does not contain any traces of the meta-fields. No response Linux 6 and 4.5.x No response The function filtermetafields was introduced by commit , which I'll provide a pull request with a test and a fix. fails to remove more than one meta-field from a fieldlist If a field list contains more then one "meta"-field, the generated documentation shows all but the first meta-field. It is a classical coding bug: the function stops removing meta fields after the first meta-field. Generated documentation contains a box with the text . The generated documentation does not contain any traces of the meta-fields. No response Linux 6 and 4.5.x No response The function filtermetafields was introduced by commit , which I'll provide a pull request with a test and a fix.


Message.locations duplicate unnecessary When running there are times the list of locations is duplicated unnecessarily, example: or as shown in this screen viewing of the 'pot' file result: <img width="1552" alt="Screenshot 2022-01-15 at 20 41 41" src="https://user-"After debugging a little, the problem appeared to be in the file: in the 'init' method. My simple solution is this: Note, this solution will probably needed to be in the and in the as well. Follow instructions on this page which comprises of sections for installing dependencies, download sources. then load the file: into an editor and search for and you will see repeated locations appear there. The message id is: There should only be ONE instance of and there are NO duplications of other locations. No response MacOS Catalina 10.15.7 9 1 No response No response No response


If a project defines "language = None" in , treat it like "en" Hello, I started working on integrating Sphinx 5 to Fedora to ensure distribution packages work smoothly when the final is out. I ran across is a side effect of the change inspired by . If a project has already "language = None" defined in their (which, it seems, used to be an issue before commit), the new behavior will cause the documentation build to error out. The projects created after the mentioned commit seem not to be affected. In a sample of ~40 packages, 2 have run across this issue. A naive check using shows that for a half a million indexed GitHub projects there is around 6k which have the string in their (I removed the commented strings from the equation). For older projects using Sphinx, this change will be disruptive and will require the same commit in the same place for each and every one of them. The exact error: Describe the solution you'd like When Sphinx encounters NoneType for language, it could set the language to English and log the fact for the user (possibly asking them to make adjustments to ) instead of erroring. It's not that different than the current behavior in 5.0.0b1. When if I run and set no language, the variable is not present at all in , although in the background my project is processed as English. Describe alternatives you've considered Aforementioned manual change for each affected project, which I'm afraid of.


Typo in new language warning See the following snippet: Both and are used incorrectly. Noticed in Read the Docs: Mention "language" without typos.


IndexError: list index out of range make[1]: [Documentation/Makefile:96: htmldocs] Error 2 make: [Makefile:1678: htmldocs] Error 2 ==ERROR: A failure occurred in build(). Aborting... archlinux Linux RYZEN 5.18.0-arch1-1 x8664 , , , , , , No response


Spurious space in default parameter values that are negative numbers in HTML output. For several projects, I've noticed a problem in the HTML output of functions that have a parameter with a default value that is a negative number. In the rendered HTML, there is a spurious space between the minus sign and the first digit. A typical example is being rendered as . This issue was originally raised with . Here are links to examples in several projects: SciPy: see . see . NumPy: Pandas: Matplotlib: I wasn't able to find an existing issue for this. I don't know which versions of Sphinx were used in all those projects, so I don't know if the problem still exists in the latest version of Sphinx. Also, it looks like those projects all use the , so it is possible that the problem is the theme and not Sphinx itself. See the links. No response See the links No response See the above comments. Probably varied; see the links. Maybe several; see the links. No response No response No response_


inheritance-diagram 404 links with SVG I have created some SVG inheritance diagrams using the plugin. If the inheritance diagram is created in a file that is not in the root directory, the links lead to a 404 page. This issue does not happen in the default (png?) mode. This issue is similar to and however this is reproduced with only first party extensions. Here is a small demo that can be used to reproduce the issue. 1) Extract the folder from the zip 2) run 3) run (I believe this is the command pycharm is running) 4) Open the website to view (I am doing this through pycharm on firefox) 5) Navigate to see that the links work. 6) Navigate to see that the links do not work. My understanding of this bug is that the links in the SVG file are relative to the SVG file (because it is embedded using the object tag) however the rest of the link is written as if it was relative to the file the SVG is embedded on. Here are the correct links to the files Below are some examples of the links generated in the SVG file. They are formatted with the link the file was embedded on followed by the actual link text in the SVG file and then the path that firefox expands that to (the link when clicked on) I would expect that the links would go to the correct page when clicked on and not to a 404 page. No response Windows 1 2 , , No response No response_


toctree contains reference to nonexisting document 'genindex', 'modindex', 'search' Is your feature request related to a problem? Please describe. A lot of users try to add the following links to the toctree: like this: See: And probably more. However when doing this we get: Describe the solution you'd like The following directive should be possible and do not rise errors: .. toctree:: :maxdepth: 1 :caption: Indices and tables genindex modindex search ``


linkcheck should check URLs of raw directives Is your feature request related to a problem? Please describe. When using a with the option, the builder does not check this URL. Describe the solution you'd like I would expect the URLs of directives to be checked by .


Use the index directive as a source for search Is your feature request related to a problem? Please describe. My problem is the search engine is not good at finding terms that are indexed, for example: should find should find should find and a few others should find should find ... Describe the solution you'd like I think using the global index as a source for the search engine is a good way to enhance this and allow people to manually boost a search result by using the bang of the index directive. (). I can try to implement it, but I'm still not sure this is a good idea. Generated Index can point to anchors, I'm not sure the current searchindex can hold them in its current state.


should improve formatting of Union, Optional, Literal, constants This is a sub-issue of split off here. When displayed normally, , , and add a lot of noise to the type signature and obscure the important information. Instead, it is much cleaner to display them using the PEP 604 () syntax: --Additionally, for it is cleaner to strip the text "Literal" and just display the literal value with normal Python syntax highlighting: -This is implemented in the tensorstore documentation via an ast transformation: This should be supported in Sphinx via a config option. The other improvement, of using syntax highlighting for constants, should also be integrated.


Smaller/wrong search index with sphinx-build -j auto Using the latest version and building with then the searchindex is considerably larger and searches work as expected. Some quick testing showed that Sphinx 6.0.0 did not have this problem while Sphinx 6.1.0 onwards does. This fails: sphinx-build -j auto -n -b html -d build/doctrees -q -E . build/html This works: sphinx-build -n -b html -d build/doctrees -q -E . build/html No response Sphinx (almost empty!) and other files are at


LaTeX: missing space before colon after "Voir aussi" for seealso directive in French Here is a screenshot ! No response This was caused by which fixed . See Sorry, my bad. LaTeX: missing space before colon after "Voir aussi" for seealso directive in French Here is a screenshot ! No response This was caused by which fixed . See Sorry, my bad.


[FEATURE] Avoid losing information in . In light to , the current implementation of does the following assuming that the builder's current translator class is not a subclass of : If one or more node classes specified by (and derived from ) are not handled by the translator class, all are transformed into nodes instead (with the same attributes). If in addition the node is not handled by the visitor class, it is transformed into an node instead as well. This implementation choice suffers from the following disadvantages: Whenever a node inherits from , the class must be to the list. A custom translator not inheriting from should not be penalized if it only implements and handle it internally. Currently, they can emulate that behaviour by implementing and checking whether the XML attributes are those that we would find on nodes. As such, I suggest the following features: Use the hook together with a meta-keyword (defaults to ) to automatically add a class derived from to the list. That way, users may still use as a regular base class without affecting the nodes expected by Sphinx itself. A custom translator class orthogonal to must satisfy one of the following exclusive conditions: explicitly supports all nodes described in by providing methods. If a node inherits from but is not in , then must explicitly specify the corresponding visitor method. That way, nodes expected from Sphinx (i.e., those in ) are correctly dispatched and the remaining nodes are simply kept as is and handled as any other nodes. specifies a generic fallback method and possibly zero or more visitor methods for handling specific nodes. The nodes are then dispatched to their most precise type. does not have an interface for nodes and should therefore use a fallback. However, if there are other post-transforms coming after the fallback transform, it would be good to keep some information on the type the node originally had before converting them into nodes. For instance, we could add as an extra XML attribute of the transformed inline node. For , since the latter does not inherit from , I suggest that the fallback implementation simply add as an XML attribute in order to have a similar behaviour.


util.inspect.objectdescription: does not emit reliable ordering for a set nested within another collection Differences appear in some v5.3.0 generated object descriptions for v1.8.1, as demonstrated by . Arguably it could make sense for code authors to intentionally write elements in their code files in a way that does not correspond to their computed sort order -- as a means to communicate with human readers about abstract ideas that aren't relevant to computers at runtime, for example. However, the current behaviour does result in non-reproducible documentation output. In particular, the ordering of a class attribute with a value that contains a set-within-a-tuple seems unreliable across differing builds: ... is emitted variously as ... ... or ... cc who has been . It is not yet clear to me exactly what circumstances cause the ordering of elements to vary - and it's OK not to proceed until that's figured out (maybe not a blocker, but it would be nice to have confidence about the cause). From searching around on previous issues while writing up this bugreport: I wonder if this could be an edge-case for / follow-up to . Although these build log links are somewhat ephemeral, the system environment details for two builds that produce differing output are visible at: https://tests.reproducible- https://tests.reproducible- No response_


Napoleon causes warning about missing end-string when encountering a reference on the first line of a docstring in a dataclass When using , a docstring of a dataclass attribute will cause an warning for a reference that's placed on the first line of this docstring. The reference itself is processed correctly. This causes the warning This one works just fine. Notice the linebreak in the docstring No response


Using rstprolog removes top level headings containing a domain directive If is set, then any documents that contain a domain directive as the first heading (eg ) do not render the heading correctly or include the heading in the toctree. In the example below, if the heading of were instead of then the heading displays correctly. Similarly, if you do not set then the heading will display correctly. This appears to have been broken for some time because I can reproduce it in v4.0.0 of Sphinx : : No response_


Allow disabling linkcheck anchor checks for specific URLs Is your feature request related to a problem? Please describe. It appears GitHub has made the Markdown renderer/file viewer require JavaScript which breaks linkcheck anchor checks. Describe the solution you'd like A config which disables the linkcheck anchors check based on a regex of the entire URL would allow for cases like these to be handled while still validating whether the page itself exists and keep anchor checks enabled for others. Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered. Additional context This is what looks like without JavaScript enabled: <img width="1007" alt="Capture d’écran 2023-07-07 à 17 00 57" src=""- Related issue:


Keep 'translated' node attribute Is your feature request related to a problem? Please describe. In my internationalized documentation, I am adding markers to untranslated or partially translated pages, to warn the user that they can see English content and nudge them to help translating (e.g., like this: !). To do this, I'm essentially duplicating part of the transform. This feels clumsy because the transform already knows which nodes are translated and which aren't. In fact, it sets an attribute on the translated ones. However, this attribute is considered internal, so it deletes it at the end: Describe the solution you'd like I'd like to know if it would be acceptable to just delete the two lines of code above in order to let extensions know whether a node has been translated. Describe alternatives you've considered Adding the functionality for "untranslated" markers to Sphinx itself.


linkcheck builder: begin using requests.Session functionality during linkchecking Is your feature request related to a problem? Please describe. At the moment, the builder performs individual (or similar HTTP request method) operations during linkchecking, without any explicit connection or session pooling. This may be inefficient, because it seems likely that for many use cases, linkchecking will make multiple requests to the same host (because documentation references are likely to have host-locality). Describe the solution you'd like Confirmation that connection pooling is not currently in use would be a good starting point; in other words: we should confirm that linkchecking of multiple URLs on a single host results in multiple TCP connections. Ideally this should be written as a test case. If we can confirm that the problem exists, then we may be able to use some of the from the library that's already in use here to enable connection pooling. Describe alternatives you've considered None so far, although open to suggestions (and improvements on the definition of this feature request). Additional context See note / suggestion about use of context managers:


source-read event does not modify include'd files source In , we use a custom extension to do some search and replace in literal blocks, see We discovered ( and ) that this does not work on all files and some are left out of this mechanism. Such is the case for include'd files. I could reproduce on Sphinx 5.0.2. something-to- my- will contain: Note that the dumping docname and source[0] shows that the function actually gets called for something-to- file and its content is correctly replaced in source[0], it just does not make it to the final HTML file for some reason. should contain: No response Linux 10 2 Custom extension using source-read event No response No response source-read event does not modify include'd files source In , we use a custom extension to do some search and replace in literal blocks, see We discovered ( and ) that this does not work on all files and some are left out of this mechanism. Such is the case for include'd files. I could reproduce on Sphinx 5.0.2. something-to- my- will contain: Note that the dumping docname and source[0] shows that the function actually gets called for something-to- file and its content is correctly replaced in source[0], it just does not make it to the final HTML file for some reason. should contain: No response Linux 10 2 Custom extension using source-read event No response No response


linkcheck failing after Sphinx 7.1.0 release Starting with , my package(s) started reporting failures due to "Anchor not found", e.g., Reverting to Sphinx 7.0.1 fixes the issue. reveals the issue started with , this PR: $ git clone $ cd photutils $ tox -e linkcheck No response No response


autodoc preserve defaults leads to exception on multiline lambda In , I've stumbled into an issue where the docs builds are failing (). After some , I learned that the issue seems to be related to the use of with and the use of where the lambda is on a different line from the . Weirdly, removing the carriage return after suppresses the error. Also, converting to a traditional decorator or replacing the lambda with a simple function also suppresses the error:


Support for functions It would be nice if there was some mechanism to automagically pick up the overloads to a function and list them together... e.g.


autodoc: Load automatically After typehints enough matured, it should be loaded automatically from autodoc extension. refs:


"Could not parse arglist" with operator pow Describe the bug With the rst I get the errors Expected behavior A clear and concise description of what you expected to happen. Environment info OS: Ubuntu 18.04 Python version: 3.6.9 Sphinx version: branches 3.x and master, but not 2.x Sphinx extensions: none Extra tools: none


Napoleon's Attributes directive ignores :noindex: option. Description of the bug Sphinxcontrib-napoleon's directive appears to ignore the option. The following reST code produces an index that includes the directives found in but leaves out all other directives: Expected behavior The above example should produce an empty document index. Environment info I am using the Sphinx packages that are provided by Ubuntu 18.04 and installed Napoleon with pip3 afterwards: The file is from https://sphinxcontrib- I used to configure my directory, edited to include and set the Python path, then typed .


Files with same name but different extensions leads to unexpected behaviour Describe the bug If there are multiple files with the same name but different file extensions; sphinx will silently choose only one to parse: To Reproduce Steps to reproduce the behavior: Given I have an extension installed to parse with: This will actually include in the document, not Expected behavior A clear and concise description of what you expected to happen. Ideally you would have a config option to specify the order of preference for file extensions, or if not set, a warning would be logged. Your project Link to your sphinx project, or attach zipped small project sample. First noted in: Screenshots If applicable, add screenshots to help explain your problem. Environment info OS: Mac Python version: 3.7.6 Sphinx version: 2.4.4 Sphinx extensions: Additional context Add any other context about the problem here. [e.g. URL or Ticket]


Breaking change to Python domain IDs Describe the bug Previously, anchors for Python functions were using underscores, changed this to dashes. To Reproduce Document some Python function whose name contains underscores: Expected behavior This used to create a fragment identifier , but since this creates . Your project This breaks links to python functions when used with : Apart from that all links (containing underscores) from external sites to Python API docs created by Sphinx (which I guess are a lot) will break!


The index directive with "builtin" type generates different index entry than the function directive and generate similar but different index entries. The former generates: The latter generates: Differences: are or not after the name of the function. are or not around "built-in function". takes one or two lines. "max" is a link or not. Link: This issue was reported on the Python bug tracker: Would be nice to unify and merge index entries generated by "function" and "index".


glossary duplicate term with a different case Describe the bug To Reproduce Steps to reproduce the behavior: Expected behavior MySQL != mysql term right ? Your project Environment info OS: Unix Python version: 3.6 Sphinx version: 3.0.0 Additional context Did occur some hours ago, maybe you just released the version https://travis-


Inconsistent handling of None by Describe the bug With , a function that returns generates a clickable link to . With , the in the signature is not clickable. To Reproduce Steps to reproduce the behavior: On running the above reproducer, note that the last two lines are: This contains a link from to the docs, but not one from to the docs. If you uncomment the line in the reproducer script and rerun it, you'll instead see: Expected behavior That in a type hint links to the documentation for the singleton regardless of whether 'description' or 'signature' mode is used. Environment info OS: Linux 4.4.0 Python version: 3.8.1 Sphinx version: 3.1.0.dev20200408 Sphinx extensions: , Additional context I installed a version of Sphinx that contains the fix for using:


for empty tuple type annotation Describe the bug Following notation for empty tuple from like I get To Reproduce Steps to reproduce the behavior: contents of snippet to module and set it to be explorable by sphinx. dependencies, in my : docs. Expected behavior Docs are built and there is with valid type annotations. Your project Environment info OS: Windows 10, but also reproduces on . Python version: 3.8.0 Sphinx version: 3.0.1 Sphinx extensions:


Decorated inherited method has no documentation Describe the bug If an inherited method has a decorator, it does not inherit the parent's doc. To Reproduce Expected behavior Both methods should be documented Environment info OS: Linux (Arch) Python version: 3.6 Sphinx version: 2.1.2 Sphinx extensions: [] Additional context Related to but calls so it should work.


BUG: Autosummary links broken in master As of commit (according to ) sphinx-gallery builds of a are failing where references to objects are no longer usable: I wondered if it was due to , but we explicitly have so I don't think so. I'll keep working on boiling this down to a more minimal example. But if anyone wants to try in the meantime, something like this should work:


Convert :kbd: to nested <kbdHTML elements Is your feature request related to a problem? Please describe. describes "a sequence of keystrokes". Sphinx converts it to a single  element: becomes Describe the solution you'd like Potentially sphinx could parse the value and convert it to individual (or nested) elements, which is what as a way to represent key combinations. Something like: Describe alternatives you've considered Alternatively the sphinx user could rewrite their markup: Related


py domain: Change a type annotation for variables to a hyperlink Is your feature request related to a problem? Please describe. py domain: Change a type annotation for variables to a hyperlink Describe the solution you'd like option was to python directives since 2.x. But it has been represented as mere text. It must be useful if it is converted to a hyperlink to the type definition. Describe alternatives you've considered No Additional context No


Sphinx, unlike Docutils, incorrectly renders consecutive backslashes Describe the bug Sphinx incorrectly renders four or more consecutive backslashes. In pure Docutils, they are renderer properly according with RST spec. To Reproduce The following snippet demonstrantes buggy rendering. Expected behavior Two backslashes should be rendered as . Three still as . Four and five as . Six as and so on. This is how it works in Docutils. Screenshots ! Environment info OS: Linux Python version: 3.6 Sphinx version: 3.0.2 Sphinx extensions: none


autosummary: The members variable for module template contains imported members Describe the bug autosummary: The members variable for module template contains imported members even if autosummaryimportedmembers is False. To Reproduce As a result, I got following output: Expected behavior The template variable should not contain imported members when is False. Your project No Screenshots No Environment info OS: Mac Python version: 3.8.2 Sphinx version: 3.1.0dev Sphinx extensions: Extra tools: No Additional context No


overescaped trailing underscore on attribute with napoleon Describe the bug Attribute name shows up as in the html (visible backslash) with napoleon. To Reproduce Steps to reproduce the behavior: empty contains run add to extensions in add to PYTHONPATH=. make clean html open in web browser and see the ugly backslash. Expected behavior No backslash, a similar output to what I get for (the type shows up differently as well, but that's not the point here) Older versions like 2.4.3 look ok to me. Environment info OS: Linux debian testing Python version: 3.8.3 Sphinx version: 3.0.4 Sphinx extensions: , Extra tools:


autodocdocstringsignature with overloaded methods When using swig to wrap C++ classes for python, if they have overloaded methods, I believe the convention is to place the signatures for each of the overloaded C++ methods at the start of the docstring. Currently, can only pick up the first one. It would be nice to be able to pick up all of them.


The default value for positional only argument has vanished Describe the bug The default value for positional only argument has vanished To Reproduce Build following document: Result: <img width="148" alt=" 2020-05-30 23 43 01" src="https://user-"Expected behavior The default value is shown. Your project No. Environment info OS: Mac Python version: 3.8.2 Sphinx version: 3.1.0dev Sphinx extensions: No Extra tools: No Additional context No


coverage ext - config to print missing coverage as warning Is your feature request related to a problem? Please describe. I run CI tests with tox and want to test my docs also. I created the following tox env but the problem is that the env does not fail on missing coverage. Describe the solution you'd like My idea is to simply add another config variable like for the extension to not only print the missing coverage to files but also as a warning to stdout (or stderr?) like the builder on broken links. Describe alternatives you've considered I considered writing a script which checks if there is content in the file and returns the appropriate exit code. The script could then be called by after the builder ran. EDIT: Added config name.


Add support for custom HTTP headers @ linkcheck Is your feature request related to a problem? Please describe. Currently, HTTP header is hardcoded: And when I hit servers that require custom headers, the only option is to add those URLs to the ignore list which is what I'd like to avoid. Describe the solution you'd like Make HTTP headers configurable. Describe alternatives you've considered Adding the affected URL to Additional context We have a GitHub Actions badge in README which then gets embedded into Sphinx docs. Running used to work but now it doesn't. After some debugging I discovered that if the HTTP query doesn't have HTTP header, it works. But the header that Sphinx injects causes GitHub's server to respond with . Interestingly, if you open this URL in a browser, it works: Google Chrome sends the following header: .


Warnings raised on variable and attribute type annotations Describe the bug autodoc signature for non-builtin types raises warning and thus fails nitpicking: To Reproduce Steps to reproduce the behavior: Create a file with the following content: Use sphinx-apidoc to generate an rst file, while enabling autodoc and intersphinx: Make sure the in the Sphinx contains Run with loud warnings and nitpicking: . You will get an error message Expected behavior I'd expect Sphinx to resolve the type annotation and possibly link both classes. Environment info OS: Linux Python version: 3.8.3 Sphinx version: 3.1.0 Sphinx extensions: , Additional context I think the issue stems from the change in which appears to try to lookup the entire type annotation as a single class. Using instead of solves this particular issue: However, it doesn't seem to work with custom classes. Take this snippet for example: This causes the following warning:


regression in 3.1.0 for methods which are s and have a type comment Describe the bug methods decorated with trigger errors similar to this when built with sphinx 3.1.0 (this worked in 3.0.4): To Reproduce Steps to reproduce the behavior: Expected behavior This should work! Your project Screenshots N/A Environment info OS: ubuntu 20.04 Python version: 3.8.2 Sphinx version: 3.1.0 Sphinx extensions: sphinx-rtd-theme, sphinx-prompt Extra tools: N/A Additional context N/A From a bisection, this is the commit which introduced the regression: CC


Support for parameterized GNU style attributes on C++ code. Hi folks. My C++ codebase uses GNU attributes for code like Unfortunately, it looks like Sphinx doesn't support them. I'm running Sphinx 3.1.1, though this functionality doesn't appear to have changed in 4. I tried to get clever with the custom attribute support you offer, but can't seem to get that to work either. Is there a right way to do this? I'd honestly be fine having the attributes stripped entirely for doc generation if there isn't another option. Even though I'm bumping up against a sharp edge, I really appreciate Sphinx. Thanks so much for making a useful tool.


autodoctypehints = 'descriptions' throws KeyError: 'module' Describe the bug autodoctypehints = 'description' does not work, results in To Reproduce Environment info OS: Linux Python version: 3.5.6 Sphinx version: 3.0.4 Sphinx extensions: , Additional context Full error message: Log file


Autodoc extension's mock file throws TypeError for generic-typed classes. Describe the bug When building the docs for a generically-typed class, a TypeError is thrown as Autodoc's attempts to concatenate a to a . See the attached log: To Reproduce Observe the docs command fails with a TypeError. Expected behavior Docs can still be built when generics are involved. Your project Environment info OS: Mac 10.15.5 (19F101) Python version: 3.7.7 Sphinx version: 3.1.1 Sphinx extensions: , , , , Additional context This might just be me not knowing how to make Sphinx-friendly generic typing, if that's the case please let me know!


:noindex: prevents cross-referencing If a flag is to a directive, it can't be cross-referenced, and no permalink to it is generated. The following ReST: generates the following HTML: I would expect only to result in no index entry, not to prevent cross-referencing or permalinking. The HTML generated for the two class directives should be the same, i.e. the HTML for the Unindexed class should be OS: Linux Mint 19.1 (based on Ubuntu 18.04) Python version: 3.8.1 Sphinx version: 3.0.0 (HEAD) but also occurs with Sphinx 2.x, 1.x


Decorated init doesn't show up in docs Subject: Decorated init won't be documented. I'm working on I have , so will be documented. But if I decorate the method, it will not show up in docs. I decorate it with , so the decorated object still has the same . I've found that the bug is due to this commit: I've printed the relevant variables in that function: And the root cause of the issue is in this line of code: Because now is not the method itself, but a decorated method, its does not contain the class anymore. This makes sphinx think it's not a method, i.e. . OS: <Unix/Linux/Mac/Win/other with version: ArchLinux Python version: 3.6 Sphinx version:1.6.5


Bad refs in pot files, when using rst_epilog To Reproduce produces with bad string numbers and "\<generated\" refs:


Regression: autodoc Dataclass variables reference target not found Describe the bug When I use and with my code which includes a dataclass with a variable of a custom type, I get a warning. To Reproduce Open the attached project . Install Sphinx. Run . Expected behavior I expect there to be no warning, or a clear message saying how I can avoid this warning. Your project Environment info macOS latest Python 3.7.7 Sphinx 3.1.2 (reproducible also with 3.1.0 but not 3.0.4)


Support mathjax 3.0 , and has a number of improvements - most notably on the speed of loading (something like an 80% decrease in load time). It would be great to get this into the Sphinx MathJax extension. The suggest that it will not be trivial to upgrade, but it may be worth it given the performance and modularity improvements. What do folks think?


Two sections called Symbols in index When using index entries with the following leading characters: £, and ← I get two sections called Symbols in the HTML output, the first containing all @ entries before ”normal” words and the second containing £ and ← entries after the ”normal” words. Both have the same anchor in HTML so the links at the top of the index page contain two Symbols links, one before the letters and one after, but both lead to the first section.


linkcheck could also check local (internal) links Subject: linkcheck currently doesn't check local (internal) links, but this would be useful. <!-- Important: This is a list of issues for Sphinx, not a forum. If you'd like to post a question, please move to sphinx-users group. !forum/sphinx-users Thanks, --See above. Create a template project with sphinx-quickstart, put the following in Run Also a check for the local link. N/A OS: Arch Linux Python version: 3.6 Sphinx version: 1.7.6


2 introduces WARNING: py:class reference target not found: Callable[[...], Awaitable[None]] Describe the bug My project, including the above function definition, builds cleanly with Sphinx 3.1.1 but with 3.1.2 I get the following warning. Note that the resulting parameter documentation does properly hyperlink and but does not get a link. https://qtrio-- To Reproduce Steps to reproduce the behavior: Expected behavior The error doesn't happen in either case and , , and all get properly hyperlinked. Your project Screenshots ! Environment info OS: Linux - Ubuntu 20.04 Python version: 3.8.3 Sphinx version: 3.1.2 Sphinx extensions: sphinxautodoctypehints sphinxqtdocumentation sphinxcontrib_trio Additional context


More customization options for figurelanguagefilename for localized images Is your feature request related to a problem? Please describe. I'm working on the localization of the , and we use a to hold the massive PO files that we use for Weblate and Sphinx. I'm now working on image localization () and I find that even though  seems to provide some customization option, it's impossible to host the localized images in the separate repository. Indeed, both the and substitution tokens resolve to absolute paths from the host system (e.g. ), and since I can't do post-processing of the subsituted string, I can't strip the base path to attempt using something like . Describe the solution you'd like I'd like the addition of one or more new path substitution tokens that can be used to customize the path to localized images more freely. For example, for this structure: and referencing , I could imagine two useful substitution tokens: Alternatively (and possible as a better solution), and could be changed to actually be relative to the Sphinx project's root folder, i.e. the in my example above, i.e.: (While the documentation currently states that these would be and , which is wrong in my tests on Linux with Sphinx 1.8.5). I don't specifically need access to the file-relative path in my use case, but I imagine that some projects may benefit from it. Describe alternatives you've considered I don't see any alternative option that would enable the workflow I want to use with localized images not being either in the original image's folder, or in one of its subfolders. Edit: We came up with ~two~ three hacks that we could use to workaround the currently limited substitution tokens offered by : Passing a class that redefines with our custom post-processing: Symlinking all localized images from the out-of-tree location to the in-tree location where Sphinx wants it: Overriding since apparently Python lets us do that, so we can do the post-processing we want: I did not test with latest Sphinx as it's not properly supported on ReadTheDocs yet, but the relevant code seems to be unchanged from 1.8.5: Additional context


Instance attributes are omitted with autosummary This issue is a followup of . Sorry, I forgot to open it. Is your feature request related to a problem? Please describe. Instance attributes are omitted when using the autosummary, as they cannot be imported. Consider the following class via will document the attribute, but via won't. Describe the solution you'd like Instance attributes should be documented, too Describe alternatives you've considered it did work before , i.e. for (although the documentation was omitted). Additional context files to reproduce the issue (including page build) Screenshot of !


Support defining specific for autodoc Is your feature request related to a problem? Please describe. Currently, if I'm using autodoc, the option does not allow specification of which private members to document. The current behavior is to document all private members, but what if I would only like to document 1 or 2? Describe the solution you'd like For to take arguments, similarly to how currently works Describe alternatives you've considered The current best way to do this is to explicitly list each class in a module and use Some prior discussion:


Error in template parameter list. Describe the bug I appear to have some valid C++14 syntax which causes Sphinx's C++ parser to choke. Here is the full error trace: To Reproduce Steps to reproduce the behavior: Expected behavior Build should succeed


Render error when combining multiple input parameters in docstring Describe the bug & Reproduce My team is writing a function in Python, which contains 3 inputs that are similar, so we want to put them in the same line in the docstring. As described in 4. Parameters in , this is possible if you write something like this: However, this produces: <img width="406" alt="" src="https://user-"Even worse, when "optional", the rendered HTML stays the same as the screenshot above, so there is no way to tell whether it is optional: Expected behavior Something like x1, x2 (arraylike, optional_) - Input arrays, description of x1, x2. Environment info OS: macOS 10.15.5 (19F101) Python version: 3.7.7 Sphinx version: 3.0.3. Extra tools: browser: Firefox 79.0a1 or Safari 13.1.1 Sphinx extensions:


Allow more compaction in gettext builder The OKFN people manually merge all generated message catalogs into a single file for upload. {{{gettext_compact}}} should support that use case too. Bitbucket: Originally reported by: Robert Lehmann Originally created at: 2011-10-11T16:43:20.007


References to figures without captions: errors in both HTML and LaTeX Describe the bug Using figures without captions causes errors in both HTML (though these are properly reported when source is processed) and in LaTeX (they are not reported until LaTeX says there were undefined references). This was the test document, compiled with sphinx 2.2.2 from pypi; was to , the project was otherwise generated with sphinx-build with no other changes. It is attached here: and these are the results: warning: WARNING: undefined label: fig-sample-nocaption (if the link has no caption the label must precede a section header) is HTML output (the error highlighted corresponds to the warning mentioned above): ! is LaTeX (pdflatex) output: ! Expected behavior I expect to produce valid LaTeX input without undefined references; figures to be referencable in LaTeX (this could be an optional setting perhaps causing uncaptioned figured to produce only "Figure 4.1." caption); about figure not being captioned to be more meaningful -- I understand that non-numbered figure cannot be referenced via :ref: (as the label will not resolve to any text) but the warning is not pointing to how to fix the issue. Environment info OS: Ubuntu 18.04 LTS Python version: 3.6.8 Sphinx version: 2.2.2 Sphinx extensions: none Extra tools: pdflatex TeXLive


Warning: Inline literal start-string without end-string in Numpy style Parameters section Describe the bug The following docstring generates a warning on the line of the timeout parameter. Removing the quote around cause the warning to go away. To Reproduce Steps to reproduce the behavior: Expected behavior I do not expect to see a warning there and was not seeing any before 3.2 Your project The project is build under the Documentation build action. Environment info OS: Mac Os and Linux Python version: 3.8.2 and 3.8.5 Sphinx version: 3.2.0 Sphinx extensions: "", "","", "", "", "", ""


locale/ translation ignored Describe the bug I read [1] as it should be possible to add a file ) and through that change translations or add additional translation to <language. When I add. [1] [2] To Reproduce Steps to reproduce the behavior: Notice that . Expected behavior The caption label for the figure (again for the sake of testing). Your project Screenshots ! Environment info OS: Arch Linux Python version: 3.7.3 Sphinx version: 2.1.2 Sphinx extensions: none Extra tools: none


All identifiers should be passed to autodoc-skip-member, even if not in all Is your feature request related to a problem? Please describe. I have a Python project for which I've generated docs. It did well. Almost everything was doc'ed. I knew about the default of excluding anything starting with '_' so I created an autodoc-skip-member function that would include those. It works. I see a bunch of private methods and functions included. But...I have a module, let's call it XYZ that has both private and public functions. Sphinx is only doc'ing the public functions of XYZ, but not its private functions. I have other modules that have private functions, and it's doc'ing those .I a print() to the autodoc-skip-member function and it doesn't even print out the of those private functions so it seems it's not even seeing it. I figured it out. The module had certain identifiers listed in , and was not passing anything else in that module to autodoc-skip-member. Describe the solution you'd like Sphinx should pass through all members, not just the ones in . Maybe add something to the object that is passed to autodoc-skip-members that indicates it would have been excluded by the designator, or some such. Describe alternatives you've considered I simply removed the from the file.


Problems with doc comments using Generic class and extending it Describe the bug This is a very specific bug (I think), when we have a class with doc comment for an attribute and I extend it. If the child class has the method (using typed parameters) and I try to reassign the attribute from class I got the following error: To Reproduce Steps to reproduce the behavior: Code example: Python script rst If you try to modify something in the script maybe the error will not appear, it's a very specific corner case! Expected behavior The warning should not appear! Your project Environment info OS: Linux 5.7.9-1-MANJARO Python version: 3.8.3 Sphinx version: 3.1.1 Sphinx extensions: related issue


TypeError: 'type' object is not iterable Hi All, this is the first time I try to create a documentation using Sphinx. venv is a virutal environment created with miniconda. Using the Miniconda3 prompt, I activated the environment and tried to create the documentation. As suggested in the error, please find below the error log. Thanks a lot for your help! PS: for privacy, I hide my absolute path calling it PATH.


docstring default arg is broken Describe the bug docstring default arg is broken in html. Python class method is rendered as To Reproduce Steps to reproduce the behavior (Dockerfile): Expected behavior A clear and concise description of what you expected to happen. Python class method is rendered as Your project Link to your sphinx project, or attach zipped small project sample. Screenshots If applicable, add screenshots to help explain your problem. ! Environment info OS: [e.g. Unix/Linux/Mac/Win/other with version] Linux Python version: [e.g. 3.7.1] 3.7 Sphinx version: [e.g. 1.8.2] sphinx-build 3.1.1 Sphinx extensions: [e.g. , recommonmark] Extra tools: [e.g. Browser, tex or something else] None Additional context Add any other context about the problem here. [e.g. URL or Ticket] None


Linkcheck should report HTTP errors instead of Anchor not found Describe the bug The command always reports that it was unable to find the anchor when  is , even when the server replied with an error status code (e.g. 404, 500). While it is indeed unable to find the anchor, the real issue is that the server encountered an error. To Reproduce Expected behavior Actual Expected output Same as when . Environment info OS: Linux 5.8.12.a-1-hardened Python version: 3.8.5 Sphinx version: 3.2.1


Generate man page section directories Current man page generation does not conform to search functionality Currently, all generated man pages are placed in to a single-level directory: . Unfortunately, this cannot be used in combination with the unix environment variable. The program explicitly looks for man pages in section directories (such as , etc.). Describe the solution you'd like It would be great if sphinx would automatically create the section directories (e.g., , , etc.) and place each generated man page within appropriate section. Describe alternatives you've considered This problem can be over come within our project’s build system, ensuring the built man pages are installed in a correct location, but it would be nice if the build directory had the proper layout. I’m happy to take a crack at implementing a fix, though this change in behavior may break some people who expect everything to appear in a directory.


Sphinx changes number system from hexadecimal to decimal for function default arguments Describe the bug When documenting a function, which requires a default argument specified in hexadecimal: Sphinx 3.2.1 will render HTML documentation where the hexadecimal value is in a different number system, than what was specified by the user (decimal), as seen in the following output from the above input: ! Expected behavior The expected behaviour would be to present the default argument in the same radix/number system as the user typed in, thus in this case the documentation would also display the value in hexadecimal. In the above example of with colors, it is unintuitive what the color might refer to, but it's easy read RGB colors in hexadecimal format - e.g. 0xffffff is white, thus which number system is used can make a huge difference. The same for example goes for e.g. specifying access rights for files () Screenshots ! Environment info OS: Mac OS X 10.14.6 Python version: 3.8.5 Sphinx version: 3.2.1 Sphinx extensions: None Extra tools: None


autodoctypehints does not effect to overloaded callables Describe the bug autodoctypehints does not effect to overloaded callables. To Reproduce Expected behavior All typehints for overloaded callables are obeyed setting. Your project No Screenshots No Environment info OS: Mac Python version: 3.8.2 Sphinx version: 3.1.0dev Sphinx extensions: Extra tools: No Additional context No


[Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version


autodoc uses a wrapper's signature for a decorated class Describe the bug uses a wrapper's signature for a decorated class. To Reproduce Branch: Steps to reproduce the behavior: In , add:. In , add: Then, run: This outputs: Expected behavior A clear and concise description of what you expected to happen. Your project Link to your sphinx project, or attach zipped small project sample. Screenshots If applicable, add screenshots to help explain your problem. Environment info OS: [e.g. Unix/Linux/Mac/Win/other with version] Python version: [e.g. 3.7.1] Sphinx version: [e.g. 1.8.2] Sphinx extensions: [e.g. , recommonmark] Extra tools: [e.g. Browser, tex or something else] Additional context Add any other context about the problem here. [e.g. URL or Ticket]


autodoctypealiases does not effect to variables and attributes Describe the bug autodoctypealiases does not effect to variables and attributes To Reproduce Expected behavior should be applied to and . Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.0 Sphinx version: HEAD of 3.x branch Sphinx extensions: Extra tools: Nothing Additional context N/A


autodoctypealiases doesn't work when autodoctypehints is set to "description" Describe the bug autodoctypealiases doesn't work when autodoctypehints is set to "description". To Reproduce I get, Then if I remove I get, Expected behavior instead of in both cases. Environment info OS: Mac Catalina 10.15.7 Python version: 3.7.9 Sphinx version: 3.3.1 Sphinx extensions: , ,


v3.3 upgrade started generating "WARNING: no number is assigned for table" warnings We've updated to Sphinx 3.3 in our documentation, and suddenly the following warning started popping up in our builds when we build either or .: I looked through the changelog but it didn't seem like there was anything related to that was changed, but perhaps I missed something? Could anyone point me to a change in the numref logic so I can figure out where these warnings are coming from?


Extend linkchecker GET fallback logic to handle Too Many Redirects Subject: linkcheck - fallback to GET requests when HEAD requests returns Too Many Redirects Bugfix Some websites will enter infinite redirect loops with HEAD requests. In this case, the GET fallback is ignored as the exception is of type and the link is reported as broken. This extends the except clause to retry with a GET request for such scenarios. Classifying this as a bug fix as URLs like used to pass the linkchecking prior to Sphinx 3.2.0 but are now failing as HEAD requests have been enforced (). /cc


autoattribute could not create document for slots attributes correctly Describe the bug autoattribute could not create document for slots attributes correctly To Reproduce The build succeeded. But docstring is not shown. Expected behavior Document should be generated successfully like when I used . Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.0 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: Nothing Additional context Nothing


Sphinx 3.2 complains about option:: syntax that earlier versions accepted Sphinx 3.2 complains about use of the option:: directive that earlier versions accepted without complaint. The QEMU documentation includes this: as part of the documentation of the command line options of one of its programs. Earlier versions of Sphinx were fine with this, but Sphinx 3.2 complains: Sphinx ideally shouldn't change in ways that break the building of documentation that worked in older versions, because this makes it unworkably difficult to have documentation that builds with whatever the Linux distro's sphinx-build is. The error message suggests that Sphinx has a very restrictive idea of what option syntax is; it would be better if it just accepted any string, because not all programs and OSes have option syntax that matches the limited list the error message indicates.


Use uplatex for default latexengine for Japanese docs Is your feature request related to a problem? Please describe. Use uplatex for default latexengine for Japanese docs. Describe the solution you'd like Since v2.3, Sphinx supports uplatex as an alternative of latexengine for Japanese docs (refs: , ). 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 latexengine for Japanese docs). Describe alternatives you've considered Nothing. Additional context Nothing.


autodoctypehints='description' does not combine well with autoclasscontent='class' With this configuration: Type hints from the method are reflected in descriptions (given explicitly in the docstrings), and are also generated for the class itself. To Reproduce Expected behavior No "Parameters" section should be to the class docs if already present for the docs simply because of the type hints. Your project Sample attached. Environment info OS: Ubuntu 18.04 Python version: 3.7, 3.8, 3.9 Sphinx version: 2.4.4 autodoctypehints="description" doesn't use init type hints Describe the bug Type hints attached to the method are not used when , but are used when . To Reproduce Create with these contents: Create with these contents: Generate documentation into an directory: Expected behavior The parameter of the constructor should have a type annotation, like the parameter of does. When , the signature does include the type annotation. Adding causes the type hint to be used, but: believe the type hint should be used even for like it is if , and causes a annotation to be , which is not helpful for a constructor and which doesn't match the behavior of (there's no in that case). Environment info OS: Linux Python version: 3.8.5 Sphinx version: 3.2.1 Sphinx extensions: and Additional context This appears to be intentional behavior as it was the fix for , but I believe it is incorrect because it is inconsistent with how signature type hints are handled.


autodoc inherited-members won't work for inherited attributes (data members). autodoc searches for a cached docstring using (namespace, attrname) as search-key, but doesn't check for baseclass-namespace. Bitbucket: Originally reported by: Anonymous Originally created at: 2011-08-02T17:05:58.754


:type: and :rtype: gives false ambiguous class lookup warnings Describe the bug The implicit xrefs created by the info fields seems to do lookup differently than explicit xref roles. For unqualified names it seems like they search for the name in every (sub)module instead of in the current module and then parent modules. To Reproduce gives the warnings which refer to the 4 unqualified type names. The . Expected behavior No warnings, and the two mentioned types should resolve to. Environment info Sphinx version: tested both with v3.3 and with master


Napoleon: Support NumpyDoc "Receives" docstring section Support the "Receives" section of NumpyDoc guidelines; it is related to Yields, which is already supported. Receives Explanation of parameters passed to a generator’s .send() method, formatted as for Parameters, above. Since, like for Yields and Returns, a single object is always passed to the method, this may describe either the single parameter, or positional arguments passed as a tuple. If a docstring includes Receives it must also include Yields.


Linkcheck crashes in 3.4.0 Describe the bug When running linkcheck in Weblate docs, it crashes with: To Reproduce Steps to reproduce the behavior: Expected behavior No crash :-) Your project Screenshots CI failure: Environment info OS: Linux Python version: 3.8.6 Sphinx version: 3.4.0 Sphinx extensions: several, but should not be relevant here Extra tools: none involved Additional context Add any other context about the problem here. [e.g. URL or Ticket]


autodoc: does not effect to variables Describe the bug autodoc: does not effect to variables. To Reproduce I expect is shown on the built document, but not shown. Expected behavior should be shown on the built document. Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No


autodoc: empty all attribute is ignored Describe the bug autodoc: empty attribute is ignored To Reproduce All foo, bar, and baz are shown. Expected behavior No entries should be shown because is empty. Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No


Attribute undocumented error for an inherited attribute Describe the bug Sphinx complains about missing documentation for an attribute of an inherited class ( is an attribute of , inherits from ). This showed up with Sphinx 3.4.0 and continues with 3.4.1. I thought this might have been the same issue as , but it has not resolved. To Reproduce Steps to reproduce the behavior: <details<summaryFull session</summary</detailsExpected behavior I expected no warnings/errors since the attribute is only inherited. Your project Screenshots n/a Environment info OS: Ubuntu Linux Python version: CPython 3.8 and 3.9 (others untested) Sphinx version: 3.4.0 and 3.4.1, was ok for <3.4 Sphinx extensions: "", "", "", "", "", "sphinxautodoctypehints", "sphinxqtdocumentation", "sphinxcontribtrio", Extra tools: n/a Additional context n/a


kbd role generates HTML that's difficult/impossible to style for compound-keystrokes Describe the bug The role doesn't mark container elements with a CSS class, so they can be styled differently that child elements representing actual keystrokes. To Reproduce For the below input the following output is generated: Now we have a problem here: there is no way to differentiate between the parent container element and the child element with CSS selectors! If we provide a CSS style to draw a border around a element, so single keystrokes are displayed correctly, then in the second example we'd get a double border (borders around the child elements, and another border around the parent element). If you want to have borders around single keystrokes, and only around the child elements in compound keystrokes, as shown on the screenshot below, the only way is to differentiate the container and child elements with a CSS class. ! Expected behavior Single keystrokes are fine as they are, no change needed: For compound keystrokes, the container element should be marked with a CSS class (e.g. ) so it can be styled differently than the child elements: Environment info OS: Windows Python version: 3.9.1 Sphinx version: 3.4.0 Sphinx extensions: - Extra tools: -


kbd role produces incorrect HTML when compound-key separators (-, + or ^) are used as keystrokes Describe the bug The role produces incorrect HTML when: 1) defining standalone keystrokes that use any of the compound-key separators (, and ) 2) defining compound keystrokes where one or more keystrokes use any of the compound-key separators (, and ) To Reproduce For the below three keyboard definitions: The following three incorrect output is generated: (1) is treated as a separator with two "blank" keystrokes around it. (2) is treated as a separator with two "blank" keystrokes around it. (3) is treated as a separator within a compound-keystroke, with two "blank" keystrokes around it. Expected behavior For single keystrokes that use , or, just a single element should be created. For compound-keystrokes, the algorithm should differentiate between , and characters appearing in separator vs keystroke positions (currently, it's very simplistic, it just treats all these characters as separators using a simple regexp). Screenshot ! Environment info OS: Windows Python version: 3.9.1 Sphinx version: 3.4.0 Sphinx extensions: - Extra tools: -


autodoc isn't able to resolve struct.Struct type annotations Describe the bug If is declared in any type annotations, I get To Reproduce Simple Simple Command line: Expected behavior If you comment out the 2 functions that have type annotations, you'll see that resolves fine and shows up in the resulting documentation. I'd expect that would also resolve correctly. Your project n/a Screenshots n/a Environment info OS: Ubuntu 18.04, 20.04 Python version: 3.8.2 Sphinx version: 3.2.1 Sphinx extensions: '', '', '', '', '' Extra tools: Additional context [e.g. URL or Ticket]


building psf/requests documentation fails with AttributeError: 'LookupDict' object has no attribute 'name' Describe the bug Since sphinx 3.4.1 building documentation fails with the following: Attached the full log: The issue is not reproducible using sphinx 3.3.1. To Reproduce In addiction to build requests' documentation I managed to reproduce the issue in the interactive python console using the following: I'm able to reproduce the issue in a clean virtualenv with only requests and sphinx installed. Thanks!


Instance variables link to other variables of the same name in the project Describe the bug Assume autodoc is used via apidoc. In theory other combinations of autodoc (or maybe even without it) can cause this to occur, but this would be the most common occurrence. If a global variable (or really, any kind of variable, just that this would be the most common occurrence) exists, and inside a class you decide to document a variable of the same name, the document of the instance variable will link to the other occurence of a variable under the same name. This can even occur across subpackages and even across other classes of those subpackages (although this appears to occur less often and seemingly...randomly? This only occurs sometimes (presumably due to the referencing heuristic?)). This is a problem, because, for example, could be and usually is completely unrelated to . Furthermore, (instance variable) could be completely unrelated to (global variable). Of course this latter example is far less likely, but the autolinking of these two together, is strange. To Reproduce Steps to reproduce the behavior: then open 127.0.0.1:8008 in a browser Expected behavior That the class variable documentation not be linked to any other. It is unreasonable to expect these to be in any way related whatsoever. If they happen to be, the user can decide to document it as such with a simple reference to the other variable, such as "see :const:\". There is no reason that a variable on some class of some database-oriented subpackage autolink to the variable on some class of some config-related subpackage (this is what occurred in my codebase, which is private at least while in development. I cannot provide anything except a heavily censored screenshot, as I do not know of a way to trick the referencing heuristic to cause a link to occur in an demo repo). Your project Screenshots Not really applicable because this is example independent but here you go anyway: ! Environment info OS: Ubuntu 14.04.5 (probably irrelevant) Python version: 2.7.6 (probably irrelevant) Sphinx version: 1.8.3 Sphinx extensions: autodoc, intersphinx, and other (probably irrelevant) extensions (todo, viewcode, githubpages in the demo repo, among others in the private repo) Extra tools: Any Browser, sphinx-apidoc


Napoleon: more custom docstring section styles Although the option help renders custom docstring section, the style is inconsistent with the rest of the doc. For example, I have a custom docstring section . I would like it to be displayed as or docstring section. However, option rendesr in a different style shown in the following picture. ! It will be really helpful if we can customize the custom sections a bit more. The following setting has a similar effect, but it renders the Parameters name instead of the custom name. I would like to do something like the following so that my Custom section has the same style as the Parameter section, and it still keeps my custom name: or The following link includes more details about the solutions: Others people have expressed a similar desire (see sphinx-contrib/napoleon) If you are interested, I would like to provide a PR for this. Thanks!


Enable passing options to pygments Hi, Related to issue 175 (and discussed on #python-docs), it would be nice to have a way of passing options to pygments. This is essential for small snippets of PHP (the :startsinline: option) - there are probably other cases too. Default options might go in , with sourcecode block options allowed. Thanks Bitbucket: Originally reported by: Paul Biggar Originally created at: 2009-06-23T19:02:39.208


reference pointing at a "rubric" directive containing a part breaks Describe the bug The reference text is broken when trying to display a reference pointing at a "rubric" directive containing a part that is. However, a title with a quoted text is rightfully displayed by a reference Will result in: ! To Reproduce Just use a directive with a quoted text in it, as shown below: from Expected behavior Text displayed by the reference should be displayed entirely Your project Environment info OS: alpine linux Python version: 3.7 Sphinx version: v3.4.1


ROI: extend dedent for code-block and literalinclude Hi, I think it would be nice to let behave like the corresponding Python one: It may just that if nod edent value is provided, then a full dedent is performed.


The reference to the same file is interpreted as a duplicate Tested on Windows 7 64bit machine, Python 2.7.3, Sphinx 1.1.3 If there is reference in various ways to the same resource, it is interpreted as different file with duplicate name. If there is a files structure as follows: And we have the following code in Then during the build of html output we will have three files (while only one is expected): The same issue is with figure directive. In attachment there is a simple Sphinx project just to illustrate the issue. IMO the problem is because all paths in Sphinx code are not normalized (() function is missing). Bitbucket: Originally reported by: Originally created at: 2013-02-18T14:47:34.934


viewcode does not work when Describe the bug viewcode does not work when To Reproduce Expected behavior Always enabled for HTML builds (except singlehtml and epub) Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No


napoleonuseparam should also affect "other parameters" section Subject: napoleonuseparam should also affect "other parameters" section Currently, napoleon always renders the Other parameters section as if napoleonuseparam was False, see source whereas it would make sense that this section should follow the same formatting rules as the Parameters section. Note the difference in rendering. See above. Alternatively another separate config value could be introduced, but that seems a bit overkill. N/A OS: Linux Python version: 3.7 Sphinx version: 1.8.1


:kbd: role with Caps Lock rendered incorrectly Describe the bug Caps Lock` produces: Expected behavior Environment info OS: Debian unstable Python version: 3.9.1 Sphinx version:


viewcode creates pages for epub even if on Describe the bug viewcode creates pages for epub even if on To Reproduce Expected behavior module pages should not be created for epub by default. Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No


sphinx-apidoc on namespaces with only subpackages/namespaces Describe the bug --implicit-namespaces allows us to use namespaces in our project tree. At the current deployed implementation (3.4.3) it makes a difference if i have a submodule in my modulepath (root python namespace) or only subpackages/namespaces. Running with a submodule (some python file) it will choose the modulepath as the one and only module otherwise, without a submodule, it will use the subpackages/namespaces as individual python modules. The difference in the output is, that the of the modulepath is not created and does contain all subpackages/namespaces as submodules and not only the root module. I would recommend to introduce an option to not search recursively for modules, or disable the recursive search if implicit-namespaces are activated. To Reproduce Steps to reproduce the behavior: Expected behavior Expecting same result in apidoc_out2, with only one module inside Instead is missing and is different. Your project Environment info OS: Win Python version: 3.8.0 Sphinx version: 3.4.3


Return type for Yield attribute not properly hyperlinked in apidocs Describe the bug Typically when one defines a return value in a method they will use the following syntax: When doing so the return type, in this case, is hyperlinked to the api docs for the appropriate data type (ie: using interphinx). However, when writing doc strings for generators using the same / similar syntax provided by the Yield attribute, the data type associated with the generator is not appropriately decorated. Taking the previous example code snippet and making a small modification as show below is sufficient to demonstrate the change in behavior: The HTML markup produced by this code snippet simply format the data type using custom font formatting based on the theme, but it fails to associate / generate the hyperlink for the API docs for the data type as is done by the Return attribute. NOTE: I am using the apidocs Sphinx extension to generate the API docs for my projects in case that has any impact on this behavior. To Reproduce Steps to reproduce the behavior: Expected behavior The data type should be decorated / marked up the same way it appears when using the Return attribute when using the Yield attribute Your project Screenshots Example output generated on ReadTheDocs: Environment info OS: MacOS Python version: 3.8.0 Sphinx version: 3.1.2 Sphinx extensions: , , Extra tools: any web browser (safari, chrome, firefox, IE) Additional context (I thought this might be a bug with the napoleon extension so I reported it here first, but they recommended I report the issue here instead)


Keeping original signatures for functions/methods I'm using Sphinx's autodoc feature to document my API. Example: The generated documentation now shows the following signature: It would be nice if there was a way to tell Sphinx to keep the name of the constant value, i.e. At the moment the only alternative is to write all signature by hand again. Bitbucket: Originally reported by: Sebastian Rahlf Originally created at: 2011-08-31T11:29:50.797


autodoc: The annotation only member in superclass is treated as "undocumented" Describe the bug autodoc: The annotation only member in superclass is treated as "undocumented". To Reproduce is not documented. It will be shown if I give option to the autoclass directive call. It seems the attribute is treated as undocumented. Expected behavior It should be shown. Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No


[LaTex] code-block printed out of margin this is not handled correctly currently: long hex strings ! code: ` link to rst file: Originally posted by in


Support C++20's spaceship operator C++20 has the new spaceship operator for three way comparisons which can also be (not sure if the latter matters to Sphinx). I hope this is a problem with Sphinx at all and not with the Breathe extension I'm also using. For example, this reST code in Sphinx currently leads to the following warning/error


Absolute/"source-relative" imports for csv-table :file: Describe the bug To be honest, I am not sure if this can be considered a bug, or if it is rather a feature request. Sorry about that. When using the directive, the use of with absolute paths are really absolute, unlike with (eg) the directive, where absolute paths are treated relative to the source directory (herein called "source-relative"). I do understand that there is a difference in the 2 cases, because with the path is not specified in . Yet, I do not see a possibility to mimic this behavior in the directive. To Reproduce A file in : Relative imports: are treated, as expected, relative to the file: Absolute imports: are treated, opposed to my expectations, like real absolute paths: and not like relative-to-source paths. Expected behavior I would expect this to work like absolute paths in the (eg) directive. But as stated in the beginning, probably I am wrong with my expectation, and this should be a feature request to add an option to use "source-relative" paths with the directive. Environment info OS: Win Python version: 3.8.5 Sphinx version: 3.2.1


Property gets linked instead of external type in class with inline type annotations Describe the bug The project is using autodoc with inline Python type annotations. Given the following class (snipped to the relevant parts): The class and method get rendered : ! In the class, the gets rendered as and is not linked. In the method, the gets rendered as and links to the property. Expected behavior I expect it to show as . A is also OK I guess (if it's meant to refer to a "traceback object"), but in that case it should link to or instead of the local property. To Reproduce I can try to create a minimal reproduction if the above is not sufficient or gets outdated. Your project Environment info OS: Linux Python version: 3.9.2 Sphinx version: 3.5.2 Sphinx extensions:


WARNING: py:class reference target not found: .. Describe the bug I think this might be referring to the ellipsis but I'm not sure at present. Note that I've already tracked the other warnings (outcomes and event type) to other issues. This time I did remember to try latest 3.x (). It showed the same issue. To Reproduce Steps to reproduce the behavior: <details<summarySteps with output including complete traceback</summary</detailsExpected behavior I'm not completely sure but at least a reference to a specific thing in my code. If it is referring to the ellipsis then perhaps it just shouldn't have an issue at all. I'm guessing it should just be a plain in the output. It could link to but that doesn't really describe it's meaning in typing and the generic type for which it is a parameter would already be linked. Your project Environment info OS: Ubuntu Linux 20.04 Python version: 3.8.3 Sphinx version: 3.2.0 Sphinx extensions: sphinxqtdocumentation sphinxcontribtrio


autodoc: duplication warning on documenting aliased object Describe the bug autodoc: duplication warning on documenting aliased object To Reproduce Expected behavior No warning Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.4 Sphinx version: HEAD of 4.0.x Sphinx extensions: Extra tools: No Additional context No


Omitting constructor signature from class header using I'm a bit surprised to see that (in the Python domain) will create a heading like which seems quite unintuitive to me, as it mixes two concepts: the declaration of "class Foo", with a constructor call "Foo(args)". How can I suppress the (automatic) addition of the constructor signature to the generated heading ? I actually want to document the constructor with an additional nested directive, and I also have an overloaded method, making the above all the more confusing. Am I missing or misunderstanding something ?


Special member is not documented with automodule Describe the bug If I have a module which has a special attribute (starting with a double underscore) it will not be documented by automodule even if it's specified in :special-members:. According to my research it's because it's not identified as an attribute. If a non-special attribute is used, everything works fine. To Reproduce To execute the build I use Expected behavior The attribute should be documented. Environment info OS: Linux Python version: 3.7.1 Sphinx version: 3.5.4


Sphinx 4.0 finds more than one target for cross-reference Hello everyone, Describe the bug After upgrading to 4.0.0 we have discovered that existing code is raising a warning with . In 3.5.4 we did not see this warning To Reproduce I have set up a minimal reproduction repository here: Steps to reproduce the behavior: Output of the sphinx-build command: Expected behavior no warning appears Your project Environment info OS: Linux Python version: 3.9.4 Sphinx version: 4.0.0 Sphinx extensions: Additional context I have bisected the issue to be introduced by Thanks verry much


Inconsistent behaviour with type alias documentation (not overwriting all the default messages, just some) Describe the bug Hello, I have 3 muiltiline docstrings for type aliases (using the next-line documentation syntax). For 1 one them the docstring is correctly shown in the rendered HTML, but for 2 of them, the docstrings are ignored and the only thing shown is the text. I suppose this is related to , but I might be doing something wrong here (so if you could point me out in the correct direction that would be very good). To Reproduce The following is a reduced example of something happening in : a directory with : I run: the path adjustment in to the generated , and to the toctree in . opening in the browser should show the reported inconsistency. Expected behavior The docs should show the contents in the docstrings for all the type aliases instead of the the default text. Your project Screenshots ! Environment info OS: Win10 WSL: Python version: 3.6.9 Sphinx version: 3.1.2 Sphinx extensions: Additional context Possibly related to


Doc rendering is incorrect when :param has datatype dict(str,str) Describe the bug I have a parameter defined under docstring of a method as:- :param dict(str, str) opcmeta: (optional) Which is being incorrectly rendered in the generated docs as:- str) opcmeta (dict(str,) –(optional) To Reproduce Create any method with the docstring containg the above param Expected behavior The param should be rendered in the generated docs as:- opc_meta (dict(str,str)) – (optional) Your project Screenshots <img width="612" alt="Screen Shot 2021-05-12 at 12 30 50 PM" src="https://user-"<img width="681" alt="Screen Shot 2021-05-12 at 12 32 25 PM" src="https://user-"Environment info OS: Mac Python version: 3.9.0 Sphinx version: 4.0.1 Sphinx extensions: ["", "", "", "autodocsumm"] Extra tools: Browser Firefox. Additional context N/A


manmakesectiondirectory should not be enabled by default Enabling by default in breaks projects relying on the previous behavior. This is a serious problem for Linux distributions that will end up with misplaced and unusable man pages. Please consider keeping it disabled by default; the benefit of being able to use MANPATH in the output directory does not justify this kind of breakage. I also noticed that the current implementation generates paths like instead of . Only the latter can be used with MANPATH which appears to be the main motivation behind . Examples of breakage I've seen so far (and we've only had sphinx 4.0.x in Arch Linux for three days): does not expect the section subdirectory and results in man pages for built-in shell commands being installed to instead of and also fails to filter out , and which are meant to be installed to . copies the output directory to resulting in paths like (note the additional directory).


New hook to customize base list I would like to change the formatting of the base list for classes. Specifially I would like to provide information about parameterized types (e.g. ]). See agronholm/sphinx-autodoc-typehints for how I want to use it. For that I need a new hook/event similar to the existing . I propose the signature . The first five arguments are exactly the same as for the existing events. The last one is the list of formatted strings generated in for the bases. It can be modified to change what is output. Alternatively, to provide even more freedom, the hook can return a string. This string is then inserted instead of the "Bases: ..." line. I can provide an implementation in a pull request, if you like the idea.


Link checker should be able to prohibit unknown redirects Is your feature request related to a problem? Please describe. A lot of links become stale or move. Good websites will provide redirects to the correct new location or return an HTTP error code. Bad websites will redirect to an unrelated page or the root of the website. Preventing all redirects does not allow links to URLs like which redirects to It needs to be possible to allow these redirects but disallow others. Describe the solution you'd like It should be possible to prohibit unknown redirects by listing all of the allowed redirects as pairs of URLs. Describe alternatives you've considered Post-process by removing filenames and line numbers then sorting it and comparing it with known good output. Additional context A link to (which used to work) now redirects to Linkcheck allows this but the original link is not valid and needs to be updated to the article's new URL of Linkcheck should be able to report an error for this redirect.


Unknown node: : : : Run: OS: Linux Python version: 3.9.4 Sphinx version: 4.0.1 Sphinx extensions: , , This is similar to the issue that was fixed in . I think, that I've tracked the issue to the plugin. This plugin connects itself to events like this however, their implementation doesn't have the snippet, which eventually leads to the above error. I could submit this as a bug report to the author of , but I wanted to make sure, that this behaviour is intended. It seems to me like a potential antipattern. For example, the above snippet (with minor variations) is already duplicated internally in - - And any plugin that connects to the event must also now add this snippet (which is complicated by the fact that doesn't seem to be available in ). Do you think that maybe the value should be resolved when the event is created in ?


[RFE] Support union types specification using | (vertical bar/pipe) Please add a support for specifying multiple types acceptable for a parameter/attribute/variable. Use case: Imagine that there is a function that accepts both and . The docstring would look like: Such a syntax is already supported by e.g. .


Linkchecker croaks on specific anchors of GitHub-rendered reStructuredText documents Dear Sphinx developers, first things first: Thanks a stack for your paramount work on Sphinx. You already saved many souls of people writing technical documentation and probably also beyond this audience. We just observed a minor woe with Sphinx' linkchecker we wanted to share with you. We really like that the linkchecker is able to check anchors within HTML documents as contributed by on behalf of . With kind regards, Andreas. Describe the bug We had the link [1] in our documentation, and, maybe after upgrading to more recent versions of Sphinx, the linkchecker suddenly started croaking on that. After changing it to [2], it worked again. When inspecting the source code of the respective HTML page, you can clearly see that the anchor name defined by is technically correct. However, it apparently has worked before by referencing . So, we are wondering if something changed on GitHub's reStructuredText renderer or even Browsers interpreting the HTML link anchors differently. When invoking those links [1,2] in the Browser, actually both work, including navigation to the appropriate place within the page. Funny, hm? [1] [2] Expected behavior Technically, from the perspective we know our way around HTML, the behavior is probably the right thing and correct. However, as we can see, something might have been changed on the HTML standard that Browsers are capable of interpreting different styles of defining link anchors. So, it might be worth to revisit this space and maybe improve the linkchecker implementation on those aspects. Environment info OS: Linux Python version: 3.9.2 Sphinx version: 3.5.2 Firefox: 86.0


Building autodocs for derived classes produces invalid warnings Describe the bug Generating API docs using the autodoc extensions, when a base class has doc strings in the constructor as well as in the class definition, and the autoclasscontent feature is set to "both", produces superfluous warnings when parsing derived classes with overloaded constructors with no doc strings on them. To Reproduce a base class with a constructor, and provide both a class doc string and a constructor doc string, something like this: a derived class that has an overloaded constructor, with no doc string, something like this: the auto content option in Sphinx to combine the class doc string and constructor doc strings together (ie: in the script) to generate the docs using the apidoc extension (ie: when using , just run ) Expected behavior Expected behavior: the API docs for both the base and derived classes should be generated without warnings. Actual behavior: docs for the base class generate correctly, but docs for the derived class produce the following warning "docstring of sample.MyDerived: WARNING: Unexpected indentation." Environment info OS: MacOS 11.3.1 (reproducible on several other Linux / Mac systems) Python version: 3.6.8 (reproducible on several newer versions as well) Sphinx version: 4.0.1 (reproducible on versions as far back as v2.2.0) Sphinx extensions: , Extra tools: (optional)


Python Enum values (used to show default values in function signatures) are rendered ugly. Python Enum values (used to show default values in function signatures) are rendered ugly. To Reproduce I made a minimal example to show the issue: Expected behavior I would hope the signature rendered as: uglyenumfunc(e: uglyenum.MyEnum = MyEnum.ValueA) → None Unfortunately, it renders as: uglyenumfunc(e: ugly_enum.MyEnum = <MyEnum.ValueA: 10) → None Environment info Python version: 3.9.5 Sphinx version: 4.0.2 Sphinx extensions: autodoc


pythonuseunqualifiedtypenames does not work on function descriptions Describe the bug When combining the new configuration with , the type names are not shortened even though links are created. To Reproduce Here's a minimal project using Sphinx 4.0.2 on Python 3.9: This produces documentation looking like this: ! Expected behavior I'd expect the link to be shortened to like it is when .


Linkcheck Reports Broken Link when Remote Server Closes on HEAD Request Describe the bug Running on a document that contains an external link to a website may report the link is broken when a web browser may successfully open the link. Specifically, if the website closes its connection when receiving the request method, then will receive a exception, which bypasses the logic that would otherwise have it make an request. A specific example of a website exhibiting this behaviour is To Reproduce Steps to reproduce the behaviour: Observe linkcheck reporting a broken link: Open in your browser Click "a link to the US Patent Website" Observe the link opening and rendering normally Expected behavior If a link is valid, and the website is returning valid content for an request, should not report the link as . Internally, in , if a call to raises a exception, it should attempt a just like it does with and . Your project Environment info OS: (but this does not appear to be OS-dependent) Python version: and Sphinx version: and Sphinx extensions: none Extra tools: any common web browser Additional context Using , we can see that this particular website closes connections when receiving : Observe that this returns the expected HTML content Observe that this fails to return any content from the server