I'm using pelican in Python to generate the static pages. It is fine to use markdown with Pygment to highlight a code block, however when it comes to the inline highlight, there is a significant difference.
Please check my page. The page is in a dark background, but the inline highlight with the back ticks `` are white background.
The markdown code is
To clearify what exactly the command returns,
one can use `pack('>i', -2500).encode('hex')`{.python}.
Or I have a more complex solution like, `''.join(r'\x%02X'
% ord(ch) for ch in src)`{.python}.
So the question here is how to define the inline highlight style?
I tried to altered the pygments default.css file in the pelican theme, but it didn't work.
I found some related links:
Inline code syntax highlighting in GitHub markdown?
Inline code highlighting in reStructuredText
Pelican uses Python-Markdown with the CodeHilite Extension to pass code blocks to Pygments. Note that code blocks do not include inline code snippets. In fact I am not aware of any Markdown parser which supports highlighting inline code. Generally, inline code snippets are too short to effectively highlight and almost always too short to take advantage of Pygments' language guessing algorithm.
I see you have attempted to inform Markdown of the language using the Attribute List Extension. However, all that does is add a class to the HTML <code> tag that wraps the code snippet. As the CodeHilite Extension only works on blocks, it never even looks at it, and certainly never passes it to Pygments.
There are a few different options you have available (each increasing in the amount of work required):
You can write your own CSS which changes the background and text color so that they match the blocks. You won't get syntax highlighting, but the inline code snippets will at least match your theme. No need to define the language here.
You could use a JavaScript code highlighting library to highlight all the code snippets based on the language you define with the Attribute List Extension. However, this may require you to redefine the CSS for the JS library so it matches the output of Pygments.
You could write your own Python-Markdown extension (or perhaps fork CodeHilite) which also highlights inline code snippets in addition to blocks.
Personally, I would recommend (1) above. In fact, looking at your page, is appears that the code blocks have the following defined:
.highlight pre, .highlighttable pre {
background: #272822;
color: #f8f8f2;
}
That is, a <pre> element with a parent assigned the "highlight" class (or the "highlighttable" class) will be displayed with those colors. As you want the same colors assigned to inline code, add the following rule:
code {
background: #272822;
color: #f8f8f2;
}
Just be sure that you define that after the styles defined by the Pelican theme (which appears to be in http://vfxware.com/theme/css/bootstrap.slate.min.css).
Sure, you could alter the existing CSS, but then if you later decide to update to a newer version of the theme or change themes entirely, you might have to redefine your own rules. Therefore, I like to define my own set of overrides in a separate file which I always make sure is the last one loaded.
I've been bitten by this all too often. My problem was that I was using an older template's old pygment.css file while upgrading the Pygment modules (CSS didn't catch up with the Pygment plugin.
In my case, the older Pygment CSS was using an HTML tag class highlight when it should be using the newer codehilite class name that newer Pygment code is now using. (Thanks to Firefox->Windows->Web Developer->Toggle menu option for pointing out this "breakage".
Replacing the pygments.css CSS-style file does the trick in restoring this much needed code syntax highlighting capability.
To regenerate the pygments.css file, execute:
pygmentize -S default -f html -a .codehilite > pygments.css
or for a darker theme, use Pygmentize monokai style, as listed in pygmentize -L:
pygmentize -S monokai -f html -a .codehilite > pygments.css
Again, problem was that Pygments changed its HTTP tag class to a newer codehilite from an older highlight.
Related
I documented some modules of a Python package I wrote using NumPy style, and I set up a readthedocs website to host the automatically generated documentation (with sphinx.ext.napoleon). Despite trying to follow the NumPy documentation style guidelines, the rendered docstrings don't appear to have the same appearance as NumPy's own documentation, which looks clearer to me. (I'm not talking about the overall html theme, but how the parameters and class methods are displayed)
My conf.py file and all .rsts of the documentation can be found in the repo. I also use nbsphinx and nbsphinx-link to render a Python Jupyter notebook, but I hope this doesn't interfere with napoleon/autodoc. I think that using numpydoc instead of sphinx.ext.napoleon isn't an option because of using nbsphinx. Also, if I'm not mistaken, using napoleon should be equivalent to using numpydoc.
How NumPy's documentation shows the parameters of a class:
How my docs shows the parameters of a class, even though I wrote the docstrings following NumPy's docs style and use sphinx.ext.napoleon with napoleon_google_docstring = False in conf.py. (Notice the dotted list, how the description of the parameter is following the name and default values in the same line...)
We want to create a sphinx documentation for our MATLAB code. Usually the themes (alabaster, readthedocs, ...) provide a sidebar, a header, a footer, a search engine and so on.
If we integrate the sphinx documentation in MATLAB this does not look so well, because the MATLAB documentation already has theses things, so the sphinx pendants are redundand.
Is there a way to create HTML pages with sphinx without all this additional stuff?
I already looked for the topics 'sidebars' here https://www.sphinx-doc.org/en/master/theming.html for instance and here on stack overflow. But nearly all questions concerned how to add MORE bars, not to remove them.
I guessed i solved the problem at least for our needs.
To remove the breadcrumbs, the sidebar and the footer in the rdt theme one must really customize the css file, where theses things are defined. Unfolded, the css file is about 6000 lines of code, which we don't want to touch.
Instead i deformed the qthelp profile a little bit. The qthelp allows to specify an alternative theme with all the options needed for it:
qthelp_theme = 'classic'
qthelp_theme_options = {
# Basic
'nosidebar': True,
'body_max_width': 'None',
'rightsidebar': False,
'stickysidebar': False,
'collapsiblesidebar': False,
'externalrefs': False,
# Styling
'footerbgcolor': '#FFFFFF',
'footertextcolor': '#1A1A1A',
...
}
This results also in a 'naked' html page without the sidebar at least, which we can customize to look more like the rtd theme.
When building the documentation we can do it twice. The first run runs with
$ make html
and the second one with
$ make qthelp
The first is for the web representation of our documentation and the second one for the MATLAB help.
I guess we can live with this solution.
You can use extensions or display helpers in IPython to make whatever syntax highlighting you'd like on output cells.
For some special cell magics, like %%javascript you can also see the input cell itself is rendered with that language's natural syntax highlighting.
How can you cause every input cell to be displayed with some chosen, non-Python syntax highlighting (regardless of any magics used on a cell, regardless of whether the cell embodies Python code, some other language).
In my case I am working with a custom-made cell magic for a proprietary language. The %%javascript syntax highlighting works well for this language, but if I have my own %%proprietarylang magic function, I obviously can't use %%javascript to help me with how the cell is displayed.
Is there a setting I can enable when I launch the notebook, or some property of the ipython object itself that can be programmatically set inside of my magic function, which will cause the same display logic to happen as if it was %%javascript.
I know that general-purpose on-the-fly syntax highlighting is not supported by the notebook currently. I'm asking specifically about how to make use of pre-existing syntax highlighting effects, such as that of %%javascript.
I've seen some documentation referring to IPython.config.cell_magic_highlight but this does not seem to exist anymore. Is there a standard replacement for it?
To replace IPython.config.cell_magic_highlight, you can use something like
import IPython
js = "IPython.CodeCell.config_defaults.highlight_modes['magic_fortran'] = {'reg':[/^%%fortran/]};"
IPython.core.display.display_javascript(js, raw=True)
so cells which begin with %%fortran will be syntax-highlighted like FORTRAN. (However, they will still be evaluated as python if you do only this.)
For recent IPython version, the selected answer no longer works. The 'config_default' property was renamed options_default (Ipython 6.0.0).
The following works:
import IPython
js = "IPython.CodeCell.options_default.highlight_modes['magic_fortran'] = {'reg':[/^%%fortran/]};"
IPython.core.display.display_javascript(js, raw=True)
Sometimes, I am working on old Python code where PEP8 was not followed at all. I could run autopep8 on the whole code but that would generate a large diff. What I want is to be able to select a block of Python code (via vim) and have just that block auto configured so that it obeys PEP8.
With C++, you can use astyle with :20,40!astyle to do just that.
Is there a vim equivalent?
Note that this is a clear example of not reading the man page for autopep8...
OK, from reading autopep8's documentation, something like:
:20,40!autopep8 -i -
or (that was actually my first idea):
:20,40!autopep8 -
should work.
The general mechanism is called "filtering" and you can read all about it in :h filter.
In the standard Python documentation, system calls appear as bold, fixed-width font. You can see this in the asyncore section, when it mentions select() or poll() for example:
http://docs.python.org/py3k/library/asyncore.html
I checked the source code for asyncore, and it has no special markups for these functions, so I'm not sure how one convinces Sphinx to do this. Is there a simple directive I can add to index.rst to make this work like I want?
Where did you see that there is no special markup for the C function calls? When I looked at the latest source for this file it has :cfunc:'select', which I think is old style Sphinx markup for C code. For the latest way of doing it read up on The C Domain.