sphinx-markdown-builder
sphinx-markdown-builder copied to clipboard
clayrisser
No output from automodule:: directive
- Module is loaded and parsed correctly (make html works)
- no markdown is rendered for the 'automodule' section.
Sphinx output:
Running Sphinx v1.8.2
making output directory...
building [mo]: targets for 0 po files that are out of date
building [markdown]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
build succeeded, 1 warning.
The markdown files are in _build/markdown.
/home/[...]/sphinx/index.rst:: WARNING: The desc element not yet supported in Markdown.
index.rst
.. Foo documentation master file, created by
sphinx-quickstart on Tue Dec 11 15:25:35 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Foo's documentation!
==============================
.. automodule:: foo.api
:members:
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
index.md
<!-- Foo documentation master file, created by
sphinx-quickstart on Tue Dec 11 15:25:35 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. -->
# Welcome to Foo’s documentation!
# Indices and tables
* [Index](https://localhost/)
* [Module Index](https://localhost/)
* [Search Page](https://localhost/)
..let me know if you can use some more info.
This plugin has no control over how things are loaded, so make sure it's not an issue with your loader. If you are confident there are no issues with your loader, then try and determine what the markdown output should be. You can base this on the html output.
This will help pinpoint which markdown feature is missing from the plugin. There are many markdown features missing as stated in the following issue.
https://github.com/codejamninja/sphinx-markdown-builder/issues/4
I understand that that the 'desc element not supported' is a separate issue, I was just including it as it was the only thing that seemed even remotely amiss in the on-screen output. ..so, to be clear, I'm not trying (with this issue) to get that to work.
..well, unless getting that warning means that all other markdown in the same module isn't rendered, which would explain the missing content.
This plugin has no control over how things are loaded, so make sure it's not an issue with your loader.
I'm sorry, loader? I don't know exactly what you're referring to -- extensions list? or something else? As far as extensions go, I only have:
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.githubpages',
'sphinxcontrib.napoleon',
'sphinx_markdown_builder',
]
As mentioned in the description originally, make html works fine. As to determining what the markdown should be -- it should include the module I referenced via the automodule directive, and its members (which are present in the HTML output, but not present at all in the make markdown output.
To be clear -- the whole module is missing. I've updated the description with more detailed information.
I can't fix it without knowing what the doctree output for that directive is supposed to be.
I'm having this same issue, except with the autofunction:: directive. Also seeing "The desc element not yet supported in Markdown." warning.
request.rst
`Request`_
----------
Functions for handling requests.
.. autofunction:: request()
request.js
/**
* Requests a URL, returning a promise
*
* @param {string} url The URL we want to request
* @param {object} [options] The options we want to pass to "fetch"
*
* @return {object} The response data
* @alias request
*/
export default function request(url, options) {
return fetch(url, options)
.then(checkStatus)
.then(parseJSON);
}
request.md
# Request
Functions for handling requests.
I expect request.md to also contain my request function description, list of params, and description of the return value, something like this:
`request()`
Requests a URL, returning a promise
Arguments:
- **url** (_string_) – The URL we want to request
- **options** (_object_) – The options we want to pass to "fetch"
Returns: **object** – The response data
make html works.
I have some work on this if you're interested -- however, I'm using Napoleon, and the mix of google docstrings style and ReStructredText was pretty awkward to deal with -- however, a significant chunk of what's needed has been created, and I can do a PR to a branch if you'd like to work on it further. In the end, it was easier and cleaner to adapt 'pydoc-markdown' to do what we wanted.
Absolutely, I'd love to see what you've done. Submit a pull request to the dev branch so I can play with it, without breaking the code.
I also am seeing this issue. The doctrees produced by Sphinx are pickled. What is the best way of getting the doctree to you?
I can generate the XML or send you pickled files?
Could you send both of them to me? Upload them to a file sharing service (like google drive) and post the link here.
I made a repo with a minimal working example. This has the source code used to generate the docs, the doctrees, and the built html and markdown.
https://github.com/utf/sphinx-automodule-example
I also converted the index.doctree to XML.
I'm also having this issue. html works fine, but I get nothing but a title with markdown.
Heads up that i have an experimental branch going here to better support common sphinx directives - including auto-doc stuff: https://github.com/manneohrstrom/sphinx-markdown-builder
Once cleaned up a bit, i'll submit a PR.
Hey, @manneohrstrom, thanks for your work. I kinda couldn't wait and pulled in some of your experimental code. 😬 Anyone who wants these latest changes, update to version 0.4.0.
I kinda redid your entire implementation of tables. I'm concerned that your implementation will not support nested tables. My implementation has not been tested with nested tables, but I am keeping track of my depth which should make it easier to implement nested tables.
I also wanted to mention, part of my table reimplementation has focused on making the tables formatted nicely in markdown.
I have documented more about tables in the following issue. #7
@eode @robertaird @utf @theobarnhart-USGS @manneohrstrom
Can you test how the tables and directives are working in your systems? I'm sure we are all using very different setups, and if you submit the issues you are having, we can build a more robust markdown builder.
@codejamninja Awesome! Sorry about the delay - work priorities came in between. I think i'll be picking this back up again in a month or two and will have time to do a more proper job! We also have extensive test cases I can run it against at that point.
I just upgraded my sphinx_markdown_builder using pip install --upgrade sphinx_markdown_builder and ran make markdown
It kind of ran and produced the following. An index.md file was produced and looks pretty good, but the links to the other modules don't work. I understand that some of these warning are due to poorly written docstrings on my part. Working on that...
(py36) ➜ docs git:(master) ✗ make markdown
Running Sphinx v1.8.3
making output directory...
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [markdown]: targets for 6 source files that are out of date
updating environment: [] 0 added, 3 changed, 0 removed
/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/numpydoc/docscrape.py:377: UserWarning: Unknown section Outputs in the docstring of None in None.
warn(msg)
/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/numpydoc/docscrape.py:377: UserWarning: Unknown section Outputs in the docstring of <function Qloss at 0x7f7a0e0772f0> in /data1/XXXXXXXXX/projects/stmarymilk/Milk_NatFlow.py.
warn(msg)
reading sources... [100%] source/stMary_NatFlow
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
/data1/XXXXXXXXX/projects/stmarymilk/docs/index.rst:: WARNING: The caption element not yet supported in Markdown.
/data1/XXXXXXXXX/projects/stmarymilk/docs/source/Milk_NatFlow.rst:: WARNING: The classifier element not yet supported in Markdown.
Exception occurred:
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx_markdown_builder/markdown_writer.py", line 312, in depart_row
self.rows.pop()
IndexError: pop from empty list
The full traceback has been saved in /tmp/sphinx-err-e7rwtk7v.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:19: recipe for target 'markdown' failed
make: *** [markdown] Error 2
The mentioned log file is below:
# Sphinx version: 3.8.3
# Python version: 3.6.8 (CPython)
# Docutils version: 0.14
# Jinja2 version: 2.10
# Last messages:
# done
#
# preparing documents...
#
# done
#
# writing output... [ 16%] index
#
# writing output... [ 33%] source/Milk_NatFlow
#
# Loaded extensions:
# sphinx.ext.mathjax (1.8.3) from /home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/ext/mathjax.py
# alabaster (0.7.12) from /home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/alabaster/__init__.py
# sphinx_markdown_builder (unknown version) from /home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx_markdown_builder/__init__.py
# sphinx.ext.autodoc (1.8.3) from /home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/ext/autodoc/__init__.py
# sphinx.ext.coverage (1.8.3) from /home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/ext/coverage.py
# sphinx.ext.viewcode (1.8.3) from /home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/ext/viewcode.py
# sphinx.ext.githubpages (1.8.3) from /home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/ext/githubpages.py
# sphinx.ext.autosummary (1.8.3) from /home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/ext/autosummary/__init__.py
# numpydoc (0.8.0) from /home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/numpydoc/__init__.py
Traceback (most recent call last):
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/cmd/build.py", line 304, in build_main
app.build(args.force_all, filenames)
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/application.py", line 341, in build
self.builder.build_update()
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 347, in build_update
len(to_build))
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 412, in build
self.write(docnames, list(updated_docnames), method)
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 593, in write
self._write_serial(sorted(docnames))
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 604, in _write_serial
self.write_doc(docname, doctree)
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx_markdown_builder/markdown_builder.py", line 61, in write_doc
self.writer.write(doctree, destination)
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/docutils/writers/__init__.py", line 80, in write
self.translate()
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx_markdown_builder/doctree2md.py", line 704, in translate
self.document.walkabout(visitor)
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/docutils/nodes.py", line 174, in walkabout
if child.walkabout(visitor):
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/docutils/nodes.py", line 174, in walkabout
if child.walkabout(visitor):
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/docutils/nodes.py", line 174, in walkabout
if child.walkabout(visitor):
[Previous line repeated 4 more times]
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/docutils/nodes.py", line 187, in walkabout
visitor.dispatch_departure(self)
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/docutils/nodes.py", line 1895, in dispatch_departure
return method(node)
File "/home/XXXXXXXXX/miniconda3/envs/py36/lib/python3.6/site-packages/sphinx_markdown_builder/markdown_writer.py", line 312, in depart_row
self.rows.pop()
IndexError: pop from empty list
Thanks so much for the bug report. This is very helpful. If you wouldn't mind, could you create a repo that reproduces this and then send me the link?
@theobarnhart-USGS, your issue has been fixed with pull request #12
Please update to v0.4.1
DISCONTINUED: This project is no longer maintained. The active version of this project is now being maintained at liran-funaro/sphinx-markdown-builder.