Is this package abandoned?

[ma-sadeghi]

Any chance this package will be updated any time soon? We want to use it as a dependency in our package, but it seems to need a bit of updating, couldn't get it to work.

[CAM-Gerlach]

@ccordoba12 Since there still appears to be interest in this package by others, unless there is a drop-in replacement, we should consider appointing a new community maintainer. If there's someone willing to contribute to help with basic maintenance, making releases and reviewing PRs, that would appear to be the responsible course of action rather than leaving it to rot. @ma-sadeghi @iwanb @scarabeusiv any interest? It likely wouldn't require much too much work for someone already familiar with the package (I'd offer to help, but I've never actually used it).

[ma-sadeghi]

@CAM-Gerlach I'm inclined to help, but not sure how much time it would require, as I'm not that familiar with the package.

[ccordoba12]

Since there still appears to be interest in this package by others, unless there is a drop-in replacement, we should consider appointing a new community maintainer

Sure, I have no problem with that. For now, it would only require to update things to work with the latest Sphinx version.

[fasiha]

Edit 1 the below has been updated after I solved the issue described initially 😄

it would only require to update things to work with the latest Sphinx version.

@ccordoba12 thanks for this note! I was able to get docrepr to generate np.sin's documentation with the following steps.

Setup: create a fresh conda environment:

conda create -n sphinx-docrepr-stuff-issue
conda activate sphinx-docrepr-stuff-issue
conda install -c conda-forge sphinx numpy ipython

Test: running the following script when inside the docrepr repo

import docrepr                                # Set module options
from docrepr import sphinxify                 # html generator
from IPython.core.oinspect import Inspector   # oinfo generator

import numpy as np

oinfo = Inspector().info(np.sin)
oinfo['name'] = 'sin'
url = sphinxify.rich_repr(oinfo)
print('file://' + url)

immediately fails, but with a few small fixes, it does work! The git diff follows:

diff --git a/docrepr/conf.py b/docrepr/conf.py
index 665ba42..6d94595 100644
--- a/docrepr/conf.py
+++ b/docrepr/conf.py
@@ -46,7 +46,7 @@ exclude_trees = ['.build']
 # TODO: This role has to be set on a per project basis, i.e. numpy, sympy,
 # mpmath, etc, use different default_role's which give different rendered
 # docstrings. Setting this to None until it's solved.
-default_role = 'None'
+default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -65,10 +65,10 @@ html_style = 'default.css'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = None
+html_title = "HTML_TITLE"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-html_short_title = None
+html_short_title = "HTML_SHORT_TITLE"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
diff --git a/docrepr/sphinxify.py b/docrepr/sphinxify.py
index f806120..60ad57a 100644
--- a/docrepr/sphinxify.py
+++ b/docrepr/sphinxify.py
@@ -172,7 +172,7 @@ def init_template_vars(oinfo):
 
     # Argspec
     tmpl_vars['argspec'] = ''
-    if oinfo['argspec'] is None:
+    if 'argspec' not in oinfo or oinfo['argspec'] is None:
         argspec = getsignaturefromtext(oinfo['docstring'], oinfo['name'])
         if argspec:
             tmpl_vars['argspec'] = argspec
@@ -262,7 +262,9 @@ def sphinxify(docstring, srcdir, output_format='html', temp_confdir=False):
         suffix = '.html'
     else:
         suffix = '.txt'
-    output_name = base_name + suffix
+    from tempfile import mkdtemp
+    destdir = mkdtemp()
+    output_name = osp.join(destdir, 'docstring') + suffix
 
     # This is needed so users can type \\ on latex eqnarray envs inside raw
     # docstrings
@@ -295,8 +297,8 @@ def sphinxify(docstring, srcdir, output_format='html', temp_confdir=False):
 
     # Create Sphinx app
     doctreedir = osp.join(srcdir, 'doctrees')
-    sphinx_app = Sphinx(srcdir, confdir, srcdir, doctreedir, output_format,
-                        confoverrides, status=None, warning=None,
+    sphinx_app = Sphinx(srcdir, confdir, destdir, doctreedir,  output_format,
+                        confoverrides,
                         freshenv=True, warningiserror=False, tags=None)
 
     # Run the app
diff --git a/docrepr/templates/layout.html b/docrepr/templates/layout.html
index 48ac59b..0bc6a55 100644
--- a/docrepr/templates/layout.html
+++ b/docrepr/templates/layout.html
@@ -10,7 +10,7 @@
 #}
 
 {# Docstring text #}
-{% if warning %}
+{% if warning and warn_message %}
 <div id="doc-warning">
     {{warn_message}}
 </div>

The diff above contains:

• three changes needed to the config,
• oinfo no longer contains argspec,
• Sphinx no longer allows the same source and destination directories, so I use tempfile.mkdtemp for the latter, and tell sphinxify to look for the HTML there,
• some changes so Sphinx prints to stdout and stderr, and finally,
• tighten the layout.html template to emit a warning only when it's actually warranted (this was missing from my initial comment).

Running the little script above produces the following output:

Full output of Sphinx (contains a number of warnings but no errors)

Running Sphinx v4.2.0
[autosummary] generating autosummary for: docstring.rst
building [mo]: targets for 0 po files that are specified
building [html]: 1 source files given on command line
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] docstring                                                                                                                                                               
/var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/docrepr-afasih/tmpkrvkvqs3/docstring.rst:1: WARNING: Inline emphasis start-string without end-string.
/var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/docrepr-afasih/tmpkrvkvqs3/docstring.rst:23: WARNING: Inline strong start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] docstring                                                                                                                                                                
/var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/docrepr-afasih/tmpkrvkvqs3/docstring.rst:22: WARNING: undefined label: ufuncs.kwargs
generating indices... done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 3 warnings.

The HTML pages are in ../../../../var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/tmpica2_zum.
Running Sphinx v4.2.0
WARNING: while setting up extension sphinx.addnodes: node class 'toctree' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_signature' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_signature_line' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_content' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_inline' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_name' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_addname' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_type' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_returns' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_parameterlist' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_parameter' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_optional' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_annotation' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_sig_space' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_sig_name' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_sig_operator' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_sig_punctuation' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_sig_keyword' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_sig_keyword_type' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_sig_literal_number' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_sig_literal_string' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'desc_sig_literal_char' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'versionmodified' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'seealso' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'productionlist' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'production' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'index' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'centered' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'acks' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'hlist' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'hlistcol' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'compact_paragraph' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'glossary' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'only' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'start_of_file' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'highlightlang' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'tabular_col_spec' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'meta' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'pending_xref' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'number_reference' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'download_reference' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'literal_emphasis' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'literal_strong' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.addnodes: node class 'manpage' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.domains.changeset: directive 'deprecated' is already registered, it will be overridden
WARNING: while setting up extension sphinx.domains.changeset: directive 'versionadded' is already registered, it will be overridden
WARNING: while setting up extension sphinx.domains.changeset: directive 'versionchanged' is already registered, it will be overridden
WARNING: while setting up extension sphinx.domains.index: directive 'index' is already registered, it will be overridden
WARNING: while setting up extension sphinx.domains.index: role 'index' is already registered, it will be overridden
WARNING: while setting up extension sphinx.domains.math: role 'eq' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'automodule' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'autoclass' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'autoexception' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'autodata' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'autonewtypedata' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'autofunction' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'autodecorator' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'automethod' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'autoattribute' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'autoproperty' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autodoc: directive 'autonewvarattribute' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autosummary: node class 'autosummary_toc' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.ext.autosummary: node class 'autosummary_table' is already registered, its visitors will be overridden
WARNING: while setting up extension sphinx.ext.autosummary: directive 'autosummary' is already registered, it will be overridden
WARNING: while setting up extension sphinx.ext.autosummary: role 'autolink' is already registered, it will be overridden
[autosummary] generating autosummary for: docstring.rst
building [mo]: targets for 0 po files that are specified
building [html]: 1 source files given on command line
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] docstring                                                                                                                                                               
/var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/docrepr-afasih/tmpkrvkvqs3/docstring.rst:22: WARNING: Inline emphasis start-string without end-string.
/var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/docrepr-afasih/tmpkrvkvqs3/docstring.rst:38: WARNING: Inline strong start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] docstring                                                                                                                                                                
/var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/docrepr-afasih/tmpkrvkvqs3/docstring.rst:9: WARNING: undefined label: ufuncs
/var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/docrepr-afasih/tmpkrvkvqs3/docstring.rst:38: WARNING: undefined label: ufuncs.kwargs
generating indices... done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 70 warnings.

The HTML pages are in ../../../../var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/tmpfpho5wtb.
file:///var/folders/h7/7nfhg5j564v87t0vbwbjy77h0000gs/T/docrepr-afasih/tmpkrvkvqs3/rich_repr_output.html

I have some questions about some of the warnings encountered by Sphinx above—are they expected?—and I also have some concerns about the formatting of the dt elements highlighted here:

but I think this is looking pretty good! What do you think?

[fasiha]

(Forgive me for pinging everyone on this thread, but I substantially rewrote my earlier comment to fix the issue I was encountering. Please re-read and feel free to share your feedback. Thanks!)