-
-
Notifications
You must be signed in to change notification settings - Fork 2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs syntax highlighting missing #591
Comments
The issue should be solved by Pygments library. Nothing to do in aiohttp itself. |
great. what is the issue? |
async/await support I mean. |
ah, so it simply fails at parsing and therefore doesn’t display stuff? makes sense, although most other highlighters are more fault tolerant |
True We are tightly coupled with sphinx for making docs. |
of course! |
Highlighting issue can be easily fixed by explicitly specifying code-block type to .. code-block:: python
import asyncio
from aiohttp import web
async def hello(request):
return web.Response(body=b"Hello, world") will be properly highlighted. Also you can see, that some code blocks with I made Proof of Concept change for fixing one block in #769. @asvetlov, I think this issue should be reopened and marked as "easy to fix", if my approach in #769 is suitable for us (if anyone want to fix this issue completely - PR is welcome). |
I prefer a new issue. |
uh, isn’t |
I used to believe |
oh, yeah, if the conf.py isn’t sufficient and somehow being explicit per code block means something else, that’s weird. |
This looks as RTD specific issue. Anyone can reproduce it with local build? I don't. |
@kxepal @asvetlov what is the reason for a new issue? I think discussion in this issue is important, no artifact were produced when the issue was closed (so nothing to invalidate), and there is no formal process that stops issue from being reopened. |
@rutsky Did the same. At least discussed Also noticed that generated HTML on RTD contains right highlight hits about the language, but the python code itself wasn't tagged with the highlight markup. No idea why. |
Reopen the issue. Maybe raising minimal versions for sphinx and pygments in requirement files will help? |
If only find which exact versions to pin... Btw, on RTD there is a build issue:
Which I don't observe locally even with the very verbose mode on ¯_(ツ)_/¯. |
@kxepal that build issue probably because docs are built on Python 3.4 in which AsyncStreamReaderMixin doesn't have iter_any: https://github.com/KeepSafe/aiohttp/blob/master/aiohttp/streams.py#L46 |
Ah, that's it! I used 3.5 and there everything is fine. Build with 3.4 indeed has no code highlight. |
@kxepal, indeed, docs built with Python 3.5 has proper syntax highlighting in my environment too! So is it possible to make RTD use Python 3.5? |
Suddenly, they only allows to choose from generic CPython 2.x / CPython 3.x, not exact version /: |
Here is related issue on RTD: readthedocs/readthedocs.org#1865 As I understand @aaugustin, this issue will be fixed with next Pygments release (probably even on Python 3.4). |
Nice! However, what I don't understand: if next Pygment release pretends to fix the issue, why |
Indeed,
|
@kxepal Yeah okay, warnings were added in sphinx-doc/sphinx#1565. But it's still highlighting the python parts for me. What I don't understand is why doesn't And just to be clear the warning are coming from blocks which are not python. i.e. the command-line examples. |
@jashandeep-sohi I can only quote myself
So what would be the fix? We seems have three ways to go:
Imho, first one is good one: we have highlighting fixed and explicit warnings about where we have a problems. With |
re the 1st & 2nd point: IMO, highlight language should be re 3rd point: Doesn't RTD use the |
@jashandeep-sohi No highlight using Pygments==2.1 with Python 3.4 for me. |
Arrrhhh...this is annoying. Can't wait for Python 3.4 to die ;-D |
@kxepal Only changes (from master) are
|
@jashandeep-sohi yeap, the first one. Would you like to submit a patch? Related build warnings need to be fixed as well I think. |
@jashandeep-sohi if |
@asvetlov Yes, please revert. Also, you might want to require The only errors/warnings I'm seeing ATM are related to |
@jashandeep-sohi fixed by f1b7c9c |
Closing the issue again. |
This fixes the syntax highlighting on readthedocs. See issue #591 of aiohttp for more information: aio-libs/aiohttp#591
starting with 0.18.0, the syntax highlighting for all but the first code block on any page vanished.
it seems some change on readthedocs, docutils or sphinx made
.. highlight:: python
not work properly.and index.rst doesn’t have that directive, so the magic for autodetecting language or whatever made it work before is also gone.
The text was updated successfully, but these errors were encountered: