0

So I'm trying to use sphinx to build some python documentation. I have an extension (https://github.com/lunaryorn/sphinxcontrib-programoutput) that I'm using to call one of my source python files to show the usage text such as .. command-output:: python ../src/something.py --help which works fine, the issue is that I want to color code the output.

I've tried putting a .. code-block:: sh on top of it but I can't figure out if there is actually a way to nest the two like that.

Is this possible at all?

Edit: More Information

So here is part of my rst source file: 

..command-output:: python ../project/module.py --help

This will end up creating html like so: 

<div class="highlight-text notranslate">
    <div class="highlight">
        <pre>
            <span></span>
            $ python ../project/module.py --help
            usage: module.py [-h][-d | -q]

            This is a project

            optional arguments:
              -h, --help            show this help message and exit

            logging arguments:
              Control what log level the log outputs (default: logger.INFO)

              -d, --debug           Set log level to DEBUG for more verbose output
              -q, --quiet           Suppress all logs except ERROR and CRITICAL
        </pre>
    </div>
</div>

The problem here is that the usage output is just straight black and white, but I would like it to be syntax highlighted as if it were shell code, or any other language (as this command-output thing might be used for other kinds of output).

As noted below https://stackoverflow.com/users/2214933/steve-piercy notes that .. code-block:: can not have another directive nested underneath it, which is something I tried to get working. So what I'm looking for would be to somehow be able to colour the output of command-output as if it were being modified by a .. code-block:: directive.

DJ SymBiotiX
  • 187
  • 2
  • 12
  • You could customize the CSS. See https://stackoverflow.com/questions/23462494/how-to-add-custom-css-file-to-sphinx and Sphinx docs on theming for more information. – Steve Piercy Oct 17 '18 at 21:31
  • While that does work for adding custom css, this won't work as the syntax highlighting in code-block:: applies classes to each word of test to colour them individually. So there isn't really a class I could just add to a div to achieve the same result. – DJ SymBiotiX Oct 17 '18 at 22:09
  • You'll have to provide a better example of your code, both source `.rst` and after `make`, and what you want to achieve. Also `.. code-block::` does not support nesting. – Steve Piercy Oct 18 '18 at 08:55
  • You are correct. I apologize for not adding more information to start with. I have updated my post with some more info. – DJ SymBiotiX Oct 18 '18 at 14:39

1 Answers1

1

First of all, sphinxcontrib-programoutput is no longer supported. I'd suggest using sphinxcontrib-autoprogram.

Both extensions generate a similar usage block (example https://docs.pylonsproject.org/projects/pyramid/en/latest/pscripts/pcreate.html), so there is no way currently to style bits in that section of the output. You may style the subsequent list of options.

You may file an issue as a feature request or modify the source yourself and submit a PR.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • I have definitely looked into autoprogram and decided that I didn't want to have to restructure every file to expose the parser from a function to get it to work. I seem to recall not necessarily liking the way it output the results. That being said, I think you've basically answered by question which is that I can't do what I want to do with the current set of items available. Thanks for taking the time to help me out! – DJ SymBiotiX Oct 18 '18 at 16:20