sphinx builder that outputs markdown files.

Overview

sphinx-markdown-builder

PyPI PyPI - Downloads PyPI - Python Version GitHub stars Liberapay receiving Liberapay patrons

sphinx builder that outputs markdown files

Please ★ this repo if you found it useful ★ ★ ★

If you want frontmatter support please use sphinx-jekyll-builder

Built by Silicon Hills LLC

index

Silicon Hills offers premium Node and React develpoment and support services. Get in touch at nuevesolutions.com.

Recommended Projects

Features

  • Generates markdown

Installation

pip3 install sphinx-markdown-builder

Dependencies

Usage

Build markdown files with Makefile

make markdown

Build markdown files with sphinx-build command

cd docs
sphinx-build -M markdown ./ build

Support

Submit an issue

Screenshots

Contribute a screenshot

Contributing

Review the guidelines for contributing

License

MIT License

Jam Risser © 2018

Changelog

Review the changelog

Credits

Support on Liberapay

A ridiculous amount of coffee was consumed in the process of building this project.

Add some fuel if you'd like to keep me going!

Liberapay receiving Liberapay patrons

Comments
  • Add table support

    Add table support

    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

    opened by clayrisser 6
  • Permit requirements to be x or higher

    Permit requirements to be x or higher

    • 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
    opened by eode 6
  • master file ..\docs\contents.rst not found

    master file ..\docs\contents.rst not found

    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.

    opened by ahalota 4
  • Preserve language domain when converting language blocks

    Preserve language domain when converting language blocks

    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
    ` ``
    
    
    opened by Liam-Deacon 4
  • failed on sphinx 1.5.1

    failed on sphinx 1.5.1

    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 '__')
    
    opened by DeoLeung 4
  • Use version ranges instead of pinning exact versions

    Use version ranges instead of pinning exact versions

    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.

    opened by software-opal 3
  • Fix markdown links

    Fix markdown links

    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

    opened by FabianNiehaus 2
  • README typo?

    README typo?

    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?

    opened by lematt1991 2
  • Class are now at a superior title level than methods

    Class are now at a superior title level than methods

    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

    opened by avaliente-bc 2
  • Classes and methods are not at the same title level

    Classes and methods are not at the same title level

    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.

    opened by avaliente-bc 2
  • update requirements file

    update requirements file

    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).

    opened by bennymeg 2
  • Add `singlemarkdown` mode to help with internal project development

    Add `singlemarkdown` mode to help with internal project development

    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.

    opened by whardier 2
  • Lists have too much blank space

    Lists have too much blank space

    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: image

    If the markdown instead were this:

    # Simple Lists
    
    * Item 1
    * Item 2
    * Item 3
    

    then it would render as: image

    opened by nedbat 1
  • Apply to be Co-Maintainer of sphinx-markdown-builder

    Apply to be Co-Maintainer of sphinx-markdown-builder

    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/

    opened by SilverRainZ 5
  • Fix table and list item: paragraph in these nodes do not need newline

    Fix table and list item: paragraph in these nodes do not need newline

    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.
    
    opened by SilverRainZ 4
  • Fix new line insertion  inside table cells text

    Fix new line insertion inside table cells text

    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.

    opened by abel-msk 0
Releases(0.5.3)
Owner
Clay Risser
Open source software engineer proficient with React, NodeJS, TypeScript and Kubernetes
Clay Risser
In this Github repository I will share my freqtrade files with you. I want to help people with this repository who don't know Freqtrade so much yet.

My Freqtrade stuff In this Github repository I will share my freqtrade files with you. I want to help people with this repository who don't know Freqt

Simon Kebekus 104 Dec 31, 2022
Legacy python processor for AsciiDoc

AsciiDoc.py This branch is tracking the alpha, in-progress 10.x release. For the stable 9.x code, please go to the 9.x branch! AsciiDoc is a text docu

AsciiDoc.py 178 Dec 25, 2022
Uses diff command to compare expected output with student's submission output

AUTOGRADER for GRADESCOPE using diff with partial grading Description: Uses diff command to compare expected output with student's submission output U

2 Jan 11, 2022
💯 Coolest snippets

nvim-snippets This was originally included in my personal Neovim setup, but I didn't like having all the snippets there so I decided to have them sepa

Eliaz Bobadilla 6 Aug 31, 2022
swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.

Master (2.4.25-SNAPSHOT): 3.0.31-SNAPSHOT: Maven Central ⭐ ⭐ ⭐ If you would like to contribute, please refer to guidelines and a list of open tasks. ⭐

Swagger 15.2k Dec 31, 2022
Data science Python notebooks: Deep learning (TensorFlow, Theano, Caffe, Keras), scikit-learn, Kaggle, big data (Spark, Hadoop MapReduce, HDFS), matplotlib, pandas, NumPy, SciPy, Python essentials, AWS, and various command lines.

Data science Python notebooks: Deep learning (TensorFlow, Theano, Caffe, Keras), scikit-learn, Kaggle, big data (Spark, Hadoop MapReduce, HDFS), matplotlib, pandas, NumPy, SciPy, Python essentials, A

Donne Martin 24.5k Jan 09, 2023
✨ Real-life Data Analysis and Model Training Workshop by Global AI Hub.

🎓 Data Analysis and Model Training Course by Global AI Hub Syllabus: Day 1 What is Data? Multimedia Structured and Unstructured Data Data Types Data

Global AI Hub 71 Oct 28, 2022
Soccerdata - Efficiently scrape soccer data from various sources

SoccerData is a collection of wrappers over soccer data from Club Elo, ESPN, FBr

Pieter Robberechts 195 Jan 04, 2023
Mayan EDMS is a document management system.

Mayan EDMS is a document management system. Its main purpose is to store, introspect, and categorize files, with a strong emphasis on preserving the contextual and business information of documents.

3 Oct 02, 2021
Type hints support for the Sphinx autodoc extension

sphinx-autodoc-typehints This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of fun

Alex Grönholm 462 Dec 29, 2022
DocumentPy is a Python application that runs in a command-line interface environment, made for creating HTML documents.

DocumentPy DocumentPy is a Python application that runs in a command-line interface environment, made for creating HTML documents. Usage DocumentPy, a

Lotus 0 Jul 15, 2021
Code for our SIGIR 2022 accepted paper : P3 Ranker: Mitigating the Gaps between Pre-training and Ranking Fine-tuning with Prompt-based Learning and Pre-finetuning

P3 Ranker Implementation for our SIGIR2022 accepted paper: P3 Ranker: Mitigating the Gaps between Pre-training and Ranking Fine-tuning with Prompt-bas

14 Jan 04, 2023
A curated list of awesome tools for Sphinx Python Documentation Generator

Awesome Sphinx (Python Documentation Generator) A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Gen

Hyunjun Kim 831 Dec 27, 2022
learn python in 100 days, a simple step could be follow from beginner to master of every aspect of python programming and project also include side project which you can use as demo project for your personal portfolio

learn python in 100 days, a simple step could be follow from beginner to master of every aspect of python programming and project also include side project which you can use as demo project for your

BDFD 6 Nov 05, 2022
Manage your WordPress installation directly from SublimeText SideBar and Command Palette.

WordpressPluginManager Manage your WordPress installation directly from SublimeText SideBar and Command Palette. Installation Dependencies You will ne

Art-i desenvolvimento 1 Dec 14, 2021
Deduplicating archiver with compression and authenticated encryption.

More screencasts: installation, advanced usage What is BorgBackup? BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports

BorgBackup 9k Jan 09, 2023
Python For Finance Cookbook - Code Repository

Python For Finance Cookbook - Code Repository

Packt 544 Dec 25, 2022
xeuledoc - Fetch information about a public Google document.

xeuledoc - Fetch information about a public Google document.

Malfrats Industries 651 Dec 27, 2022
Compare two CSV files for differences. Colorize the differences and align the columns.

pretty-csv-diff Compare two CSV files for differences. Colorize the differences and align the columns. Command-Line Example Command-Line Usage usage:

Devon 6 Dec 29, 2022
Que es S4K Builder?, Fácil un constructor de tokens grabbers con muchas opciones, como BTC Miner, Clipper, shutdown PC, Y más! Disfrute el proyecto. <3

S4K Builder Este script Python 3 de código abierto es un constructor del muy popular registrador de tokens que está en [mi GitHub] (https://github.com

SadicX 1 Oct 22, 2021