pdoc3 / pdoc

:snake: :arrow_right: :scroll: Auto-generate API documentation for Python projects
https://pdoc3.github.io/pdoc/
GNU Affero General Public License v3.0
1.12k stars 145 forks source link

sub-Module-level variables not documented #391

Open apassy opened 2 years ago

apassy commented 2 years ago

Expected Behavior

Top-level variables from module file documented, e.g. SQL_SERVER_MAX_VALUES_IN_INSERT = 1000 #: The maximum number of values in an insert statement for sql server

Actual Behavior

They don't show up in documentation

Steps to Reproduce

1.define submodule in Module

  1. add variable
  2. run pdoc --html -o ./docs --force ./

Additional info

structure: Top-level |- init.py (empty) |- submodule.py (with variable of interest)

apassy commented 2 years ago

NM, only pep224 docs work.

Maybe add to docs?

kernc commented 2 years ago

Variable doc-comments were introduced in https://github.com/pdoc3/pdoc/pull/292. Your example works for me with the latest version.

$ mkdir foo

$ touch foo/__init__.py

$ cat >foo/foo.py <<EOF                                                             
SQL_SERVER_MAX_VALUES_IN_INSERT = 1000 #: The maximum number of values in an insert statement for sql server

EOF

$ tree foo
foo
├── foo.py
└── __init__.py

0 directories, 2 files

$ pdoc foo.foo
Module foo.foo
==============

Variables
---------
`SQL_SERVER_MAX_VALUES_IN_INSERT`
:   The maximum number of values in an insert statement for sql server

$ pdoc --html foo
html/foo/index.html
html/foo/foo.html

$ grep SQL_SERVER_MAX_VALUES_IN_INSERT html/foo/foo.html 
<pre><code class="python">SQL_SERVER_MAX_VALUES_IN_INSERT = 1000 #: The maximum number of values in an insert statement for sql server</code></pre>
<dt id="foo.foo.SQL_SERVER_MAX_VALUES_IN_INSERT"><code class="name">var <span class="ident">SQL_SERVER_MAX_VALUES_IN_INSERT</span></code></dt>
<li><code><a title="foo.foo.SQL_SERVER_MAX_VALUES_IN_INSERT" href="#foo.foo.SQL_SERVER_MAX_VALUES_IN_INSERT">SQL_SERVER_MAX_VALUES_IN_INSERT</a></code></li>