sphinx-doc processing

Philippe's Avatar


11 Jun, 2017 10:47 AM

dear Brett,
My goal is to use Marked to automatically process sphinx (http://www.sphinx-doc.org) files through the Custom Processor.
I'm aware that one can use the rst2html processor to have a first idea of the rendering, but all the sphinx-based directives are not processed, of course.

I've searched without success if somebody already did this job; and tweaked a bit, without success too.

My best bet is to :
- put in Custom Processor>Path the path where the sphinx-build file is: ~/sphinx/bin/sphinx-build
- put in Custom Processor>Args this: -c ./ -b html -d build/doctrees source build/html
also tried: -c ./conf.py -b html -d build/doctrees source build/html

When asking to render a sphinx file, Marked doesn't display any HTML rendering of the file and warns "Error: Config directory doesn't contain a conf.py file"

What's wrong?
thanks for your help!

  1. Support Staff 1 Posted by Brett on 14 Jun, 2017 03:05 PM

    Brett's Avatar

    Where is your conf.py file located? You need to specify an absolute path
    for that, as when Marked executes the processor it's running out of its
    own shell and doesn't know at the time of execution what the home folder
    or containing document folder is.

    That information is passed [via environment
    though, so if you need to have a dynamic reference to different config
    files, you can make a wrapper shell script that sets the current working
    directory prior to execution.


  2. 2 Posted by Philippe on 14 Jun, 2017 03:41 PM

    Philippe's Avatar

    Thank you, Brett, for your reply.

    The conf.py is in the same folder where the source file to be rendered is. I tried to specify the whole path without succeeding to compile with Marked, again.
    My files are within an activated virtualenv, do you think it would be a problem? If so, I've to tell Marked how to find the files in this virtualenv. Do you know how to do?

  3. Support Staff 3 Posted by Brett on 14 Jun, 2017 04:28 PM

    Brett's Avatar

    I'm not well versed in virtualenv. I use rvm with Ruby, and it allows
    the creation of "wrappers" that will load the appropriate environment
    prior to executing. Is that something virtualenv can do?

    By creating a basic shell script, you can add commands to load and set
    environment variable prior to executing the script. Keep in mind that
    you're not referencing a file, Marked is passing the file contents to
    the script, so you'll need to `cat | [your command]` and pass the result
    back out to STDOUT.


  4. 4 Posted by Philippe on 15 Jun, 2017 11:12 AM

    Philippe's Avatar

    hi Brett,
    thx for your comprehensive reply. I shall dig deeper the Python wrappers.
    However, do you think the shell scripts are mandatory for launching Sphinx rendering? And, if so, would you like to pinpoint to me an example script doing that kind-a process (w/ other engines, of course).
    thx & best,

  5. Support Staff 5 Posted by Brett on 15 Jun, 2017 03:15 PM

    Brett's Avatar

    I don't know for certain that a shell wrapper would be necessary, it
    just sounds like it works from your command line because it's loading an
    environment that isn't accessible to Marked. The primary reason would be
    because you can then use variables in the paths to set config and build
    directories, e.g.:

    /Users/you/sphinx/bin/sphinx-build -c ./ -b html -d
    ${MARKED_PATH}/build/doctrees source ${MARKED_PATH}/build/html


Reply to this discussion

Internal reply

Formatting help / Preview (switch to plain text) No formatting (switch to Markdown)

Attaching KB article:


Attached Files

You can attach files up to 10MB

If you don't have an account yet, we need to confirm you're human and not a machine trying to post spam.

Keyboard shortcuts


? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac