'sourcecode' vs. 'code-block' in the User Manual.

Create issue
Issue #38 resolved
David Williams created an issue

In the user manual we use 'code-block' to denote a section of syntax highlighted code. This seems to work fine when run through our external tools, but it does not preview correctly in BitBucket (the code snippets are missing).

For example, see here: https://bitbucket.org/volumesoffun/polyvox/src/7d0fc3e3d222/documentation/Lighting.rst?at=develop

Replacing 'code-block' with 'sourcecode' (as described in the official BitBucket Wiki docs) allows the source code snippets to preview correctly.

For example, see here: https://bitbucket.org/volumesoffun/polyvox/src/7d0fc3e3d222/documentation/ErrorHandling.rst?at=develop

Should we switch to using 'sourcecode'? I didn't find any information on what the difference is.

Comments (3)

  1. Matt Williams

    Sphinx (our manual tool) is based on Docutils (which is the official implementation of reStructuredText). Until recently docutils had no support for source code highlighting and so Sphinx added their own in as code-block. In a recent release of docutils they added effectively the same capability but called sourcecode. This is why Bitbucket (which just passes the text file through plain docutils) doesn't support code-block.

    It looks like Sphinx now essentially supports code-block as an alias for sourcecode (or vice-versa, I'm not sure). Therefore, I suggest that we use sourcecode everywhere in our manual so that the Bitbucket previews work.

  2. Log in to comment