Readthedocs.org: Code formatting works locally but not on ReadTheDocs.org

[amit1rrr]

Details

• Read the Docs project URL: docs.nurtch.com
• Build URL (if applicable):
• Read the Docs username (if applicable): amit.[email protected]

Expected Result

I am expecting python code snippets to be syntax highlighted on ReadTheDocs.org. It's working fine locally where I have readthedocs theme installed. I am using code block. Here is the snippet example inside .rst file:

   .. code-block:: python

      from rubix.aws.cloudwatch import plot_metric

      # Load balancer P90 latency with deployment time markers
      plot_metric(namespace='AWS/ELB',
            metric_name='Latency',
            dimensions={'LoadBalancerName': 'prod-xyz-lb'},
            markers=deployment_times,
            statistics='p90')

      # Maximum CPU Utilization across EC2 for a specific time period
      plot_metric(namespace='AWS/EC2',
            metric_name='CPUUtilization',
            start_time=datetime.datetime(2018, 04, 25),
            end_time=datetime.datetime(2018, 04, 26)
            statistics='Maximum')

Screenshots attached.

Local Build.

On my hosted domain

[ivankravets]

The same problem http://docs.platformio.org/en/latest/projectconf/advanced_scripting.html#before-pre-and-after-post-actions

[ivankravets]

It seems duplicate of https://github.com/rtfd/readthedocs.org/issues/4050

[amit1rrr]

It seems duplicate of #4050

Yes, looks like the same issue. Workaround is to explicitly specify the version of sphinx_rtd_theme package sphinx_rtd_theme>=0.3.1

I don't have any requirements.txt in my repository. There is one scant reference to it in the docs:
http://docs.readthedocs.io/en/latest/faq.html?highlight=requirements.txt#my-project-isn-t-building-with-autodoc

Looks like I need to go to Advanced settings and enable build with virtualenv and specify the requirements.txt file there. My questions is: what are all dependencies of building RTD.

Should these be enough?
https://github.com/shawnbrown/datatest/commit/66f845531854692f74725e5fab1037f418a25695

[amit1rrr]

EDIT: This doesn't work. Not permanently at least. See my comment below.

My issue is resolved.

Steps for other folks:

• Go to Advanced Settings and select this option: Install your project inside a virtualenv using setup.py install
• Add requirements.txt file to the text box on Advanced settings (see screenshot)
• Scroll down and select this option as well: Give the virtual environment access to the global site-packages dir. (see second screenshot)
• Create requirements.txt file in your project root with only this line:
  sphinx_rtd_theme>=0.3.1
• Commit the project and verify that the build succeeds on RTD.
• Code should have syntax highlighting

Screenshots:

[RichardLitt]

Thank you, @amit1rrr, for both logging and resolving your issue! Glad you got it fixed.

[ivankravets]

@RichardLitt I'm not sure that a thousand developers should do the same. I think it should be fixed on RTFD side.

[stsewd]

@ivankravets yeah, we didn't update the package on rtd because of a previous bug on the 0.3 version of the theme. But now that is fixed.

[amit1rrr]

After I followed those steps a couple of builds went fine and now I started seeing this error on RTD:
python: can't open file 'setup.py': [Errno 2] No such file or directory

And rightly so, because if we have selected to install a project inside virtual env with setup.py then we need to write our own setup.py :( I am not sure why it succeeded the first few times.

Now spending time writing a setup.py to get my original issue of code formatting working is not worth it. @stsewd since the theme issue is fixed can of you update the package on rtd?

[amit1rrr]

I just made an attempt at simple setup.py that worked.
https://github.com/amit1rrr/nurtch-docs/blob/master/setup.py

Everyone shouldn't have to do all this to get syntax highlighting working for code blocks. Seems like an essential feature for any documentation system is broken in RTD.

[stsewd]

I can say that the Install project option isn't required for your project, you only need the requirements.txt file

[amit1rrr]

@stsewd I just tried deselecting the Install Project option and only keeping the requirements.txt and code formatting is gone. I enabledInstall Project option again but still no code formatting. I pushed an empty commit to trigger a build still no code formatting.

I am terrified at inconsistent result of RTD builds with same configuration and same code. We should have an ability to replicate RTD build steps locally.

[stsewd]

That's weird, can you please try to wipe the environment before doing a build? You can do this on the Versions section.

[stsewd]

Also, you can re-build your docs manually from the Builds section

[amit1rrr]

Worked fine after wiping. I think the sphinx_rtd_theme package would have got cached or something. Shouldn't wipe be default step on internal RTD builds.

[stsewd]

Yes and no, I mean, the wipe feature is for doing a clean installation, that would be a waste of resources for rtd doing it on each build. This step is almost no need it, just in exceptional cases like this one.

[amit1rrr]

This step is almost no need it, just in exceptional cases like this one.

I'm not sure about that. I have had inconsistent results twice in my first 2 weeks with RTD (documented in this thread above). When there is nothing exceptional in my build/package/config.
If it's package caching issue then at least every build that specifies requirements.txt should have wipe option enabled.

[stsewd]

We can close this, as the original issue was solved. I think there is already a follow up by the rtd team to upgrade the theme on the rtd side.

[ivankravets]

@stsewd I did “wipe” for docs.platformio.org and it still doesn’t work without a custom requirements.txt

Should it work without extra steps as in the previous years?

[stsewd]

@ivankravets yes, you need a requirements file with the rtd_theme version that fixes the syntax.

[stsewd]

And as mention, rtd only needs to upgrade the default version of the theme and then you wouldn't need a requirements file.

[ivankravets]

Do you have any ETA when you will have this fixed on your side?

[morenoh149]

the follow up issue should be shared here for those interested

[stsewd]

@ivankravets @morenoh149 Please see this comment https://github.com/rtfd/readthedocs.org/issues/4050#issuecomment-386040786

[davidfischer]

Do you have any ETA when you will have this fixed on your side?

Probably within a week. We generally don't limit ourselves with strict timelines.

[morenoh149]

that's odd, this issue and the one you shared say the issue is fixed. What would it take to get https://solidity.readthedocs.io/en/v0.4.23/solidity-by-example.html working? because the issue https://github.com/ethereum/solidity/pull/4125#issuecomment-388964876 said to track this issue (this thread).

[davidfischer]

I re-opened #4050 until #4096 is merged. I think that's for the best so people can find it.

As to what it takes to get this working now, you need to pin to sphinx_rtd_theme>=0.3.1. Both of the two threads discuss that.