I have already implemented table support, but I'm am not sure how well it works across different setups. Feedback would be much appreciated.

I am keeping track of where I am in the table to hopefully make it easy to add support for nested tables in the future. Keeping track of where you are is a simple pop/push operation. Push (append) the current node to the node type array when the node is entered, and pop it off the node type array when the node is departed.

    def visit_table(self, node):
        self.tables.append(node)

    def depart_table(self, node):
        self.tables.pop()

Notice that I'm doing this with other nodes besides the table node. For example, I do this with thead, tbody and row.

    def visit_row(self, node):
        if not len(self.theads) and not len(self.tbodys):
            raise nodes.SkipNode
        self.rows.append(node)

    def depart_row(self, node):
        self.add('|\n')
        if not len(self.theads):
            self.row_entries = []
        self.rows.pop()

Keeping track of where you are in the table (basically reference counting) simplifies the code. Instead of using integer counters, I am using arrays of nodes. This allows referencing the nodes from other visit methods. This can come in handy quite often. For example, I use the "reference counting node arrays" to generate padding in the table entries making the tables look much prettier.

Basically, I am finding the largest string in a column and using it to calculate the padding. This would be very challenging if I did not have access to nodes outside of the current node.

    @property
    def rows(self):
        rows = []
        if not len(self.tables):
            return rows
        for node in self.tables[len(self.tables) - 1].children:
            if isinstance(node, nodes.row):
                rows.append(node)
            else:
                for node in node.children:
                    if isinstance(node, nodes.row):
                        rows.append(node)
        return rows

    def depart_entry(self, node):
        length = 0
        i = len(self.row_entries) - 1
        for row in self.rows:
            if len(row.children) > i:
                entry_length = len(row.children[i].astext())
                if entry_length > length:
                    length = entry_length
        padding = ''.join(_.map(range(length - len(node.astext())), lambda: ' '))
        self.add(padding + ' ')

https://github.com/codejamninja/sphinx-markdown-builder/blob/master/sphinx_markdown_builder/markdown_writer.py#L320-L329

I am thinking about possibly implementing this reference counting across all of the nodes. It could simplify the design of some of the more complex transpiling.

Please discuss the reference counting more at the issue below. #8

• Allow higher versions of Sphinx
• Lower versions of Sphinx may work, but haven't been tested
• Sphinx limited to version < 2
• All other libraries unrestricted, but should later be restricted if breaking changes are made, or if they are found to use semantic versioning and can be range-limited, as done with Sphinx

I have sphinx-build 1.8.3.

From what I've been following, I only need an index.rst file initially. When I try to run make markdown, it's looking for a file .\docs\contents.rst , which by default I don't have.

I assume this might be configured to work with an older version of sphinx that included a contents.rst by default?

I created a contents.rst file and put some dummy content in, and then it ran just fine.

Markdown conversion does not preserve restructuredtext code blocks such as:

.. code-block:: python
    import math

.. literalinclude:: test.py
    :language: python

.. highlight:: bash

::
    cat *.rst

And render it in markdown as (without the spaces I've used as escape characters for the backticks):

`` `python
import math
` ``

...

`` `bash
cat *.rst
` ``

better to support some older versions, on 1.5.1 it fails with

sphinx-build -b markdown doc/ doc/_build/ -E
Running Sphinx v1.5.1
/xxx/.virtualenvs/log/lib/python3.6/site-packages/matplotlib/font_manager.py:232: UserWarning: Matplotlib is building the font cache using fc-list. This may take a moment.
  'Matplotlib is building the font cache using fc-list. '

Extension error:
Could not import extension sphinx_markdown_builder (exception: cannot import name '__')

I'm trying to use your library on Python 3 and with Sphinx 2.0.1, and I have noticed that your package pins every package it depends on, this makes it very difficult to use new Sphinx versions.

Cross references between markdown files created from auto-generated documentation via sphinx-apidoc were all listed as [...](#None).

This was due to faulty return values for markdown_builder.get_target_uri() and doctree2md._refuri2http().

See #20

I'm a bit confused about the "Usage" section of the README:

from sphinx_markdown_parser.markdown_builder import MarkdownBuilder

source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown'
}

def setup(app):
    app.add_source_suffix('.md', 'markdown')
    app.add_source_parser(MarkdownParser)

Should this be from sphinx_markdown_builder.markdown_build import MarkdownBuilder instead of from sphinx_markdown_parser.markdown_builder import MarkdownBuilder. Also I think app.add_source_parser(MarkdownParser) should be app.add_source_parser(MarkdownBuilder), otherwise, where is MarkdownParser imported from/defined at?

When I did PR #38 I made a mistake resulting in classes being at an inferior title level than methods while the opposite was expected. It is now fixed

Today, when generating markdown files, classes and methods from theses classes appears at the same title level which is kind of annoying. I put classes at a higher level than methods to fix this.

Is it possible to remove the strict version matching for the required packages in favor of the greater then equals sign (>=) ?

The package fails on newer versions of sphinx (i.e. 2.2.0) which also installs newer version of docutils (0.15.x).

Being able to produce a single README.md that has the entire output would be valuable for teams using products like GitHub that want to make sure there is "go to" documentation for every repository.

This .rst:

Simple Lists
------------

- Item 1
- Item 2
- Item 3

is output as:

# Simple Lists


* Item 1


* Item 2


* Item 3

When rendered, this puts too much space between the list items.

It renders on GitHub like this:

If the markdown instead were this:

# Simple Lists

* Item 1
* Item 2
* Item 3

then it would render as:

I had sent mail to you but get no response, so I file issue here :)

Hello clayrisser,

I am a power Sphinx user[1] and I wrote many Sphinxextensions[2].

sphinx-markdown-builder is a awesome project, but it has some BUGs. I filed a PR[3] to fix one of theme, I hope it can be merged. But it seems that you are no longer active on this project. Contribute is always better than fork, can I apply to be the co-maintainer of this project?

If you agree, please also add me[4] as Co-Maintainer on pypi.

[1] https://github.com/SilverRainZ/bullet/blob/master/conf.py [2] https://github.com/sphinx-notes [3] https://github.com/clayrisser/sphinx-markdown-builder/pull/57 [4] https://pypi.org/user/SilverRainZ/

-- Best regards, Shengyu Zhang

https://silverrainz.me/

A paragraph maybe child of a table entry or list item, we should not add newline in these cases. See commit message and comments of code.

Table

rST source:

.. list-table::
   :header-rows: 1

   * - Type
     - Variant
   * - ``any``
     - ``Stream``
   * - ``comparable``
     - ``Comparable``

Generated markdown:

| Type

 | Variant

 |
| ------------------- | ---------------------------------------------------------------- |  |  |
| `any`

                 | `Stream`

                                                           |
| `comparable`

          | `Comparable`

                                                       |

After this patch:

| Type | Variant |
| ------------------- | ---------------------------------------------------------------- |  |  |
| `any`                 | `Stream`                                                           |
| `comparable`          | `Comparable`                                                       |

List

rST source:

1. Use ``FromSlice`` to construct a stream of int slice.
2. Use ``Filter`` to filter the zero values.
3. Use ``ToSlice`` convered filtered stream to slice, evaluation is done here.

Generated markdown:

1. Use `FromSlice` to construct a stream of int slice.


2. Use `Filter` to filter the zero values.


3. Use `ToSlice` convered filtered stream to slice, evaluation is done here.

After this patch:

1. Use `FromSlice` to construct a stream of int slice.
2. Use `Filter` to filter the zero values.
3. Use `ToSlice` convered filtered stream to slice, evaluation is done here.

rst table construction:

.. table:: Тест
    ====== ==============================================================================
    х1      x2
    ====== ==============================================================================
    d1     d2
           d4
    d5     d6       
    ====== ==============================================================================

converted to wrong syntax

. . . 
| d1  | d2
d4
|
. . . 

It is incorrect in terms of Markdown. All table cell context should be in one line. So I fix this. I test it using methods overload in conf.py in my current sphinx-doc documentation.

For mow it produce

| х1 | x2 |
| ------ | ------------------------------------------------------------------------------ |
| d1 | d2<br>Переменные события пересечения порога для метрики объекта |
| d5 | d6 |

Unfortunately, It steels has problems with correct column width detection ( made some trick in this example) and i steel work on solution.