Compatible links between GitHub and Sphinx...

[lrmoreno007]

Hello, I'm trying to fix some links in the documentation of this project (and my translation to Spanish) and I can't find a way to make the links compatible on GitHub and Sphinx (ReadTheDocs).

=====================================

If I use this method:
´´link to readme <esp8266/readme.rst>´´
The links work perfectly on GitHub, but don't work on Sphinx.

Example in this project: Click in the link "Generic ESP8266 modules"
https://github.com/esp8266/Arduino/blob/master/doc/faq/a01-espcomm_sync-failed.rst
https://arduino-esp8266.readthedocs.io/en/latest/faq/a01-espcomm_sync-failed.html

========================================

If I use this method:
: doc: `link to readme <esp8266wifi/readme>`
The links work perfectly on Sphinx, but don't work on GitHub.

Example in this project: Click in the link "ESP8266WiFi library documentation"
https://github.com/esp8266/Arduino/blob/master/doc/libraries.rst
https://arduino-esp8266.readthedocs.io/en/latest/libraries.html

===============================================

Can someone help me to fix it?

Regards.

P.D.: Change this " ´ " for " ` " in my examples.

[devyte]

I've come across the same, and I have no idea how to resolve it.

[mgeier]

I came here from the Sphinx mailing list: https://groups.google.com/forum/#!topic/sphinx-users/ZoYI_-ZKMDw

You could try to make a little Sphinx extension with a Transform class that rewrites your "normal" links to :doc: links.

I've used a similar thing there:
https://github.com/spatialaudio/nbsphinx/blob/6edd6993851e8dbd0bf6fee91aab55297e04be9a/src/nbsphinx.py#L1004-L1088

Note that my example does several more things, you would only need a part of the code.

BTW, with Sphinx 2.0 you will have to use refdomain='std' instead of refdomain=None, see spatialaudio/nbsphinx#111.

[lrmoreno007]

Thanks for the response @mgeier , but I tried to make it and I don't get it. Could you help us ?, please.

[mgeier]

I've already tried to implement this, and it turned out to be more complicated than I thought ...

I'm currently also stuck, I'm waiting for help from there: https://groups.google.com/forum/#!topic/sphinx-dev/bNW2Tc4hhOA

[lrmoreno007]

Ok, I'll pay attention.

I do not understand how this has not been corrected yet, it is very very basic to maintain compatibility between Github and Readthedocs. And it's as simple as replacing .rst with .html, but automatically.

BTW, where I must change to " refdomain='std' ". In conf.py?

[mgeier]

OK, I got an answer from the Sphinx mailing list and with its help I implemented this: spatialaudio/nbsphinx#173

If you don't mind the additional dependencies, you can just install and activate nbsphinx (including the above PR) and your links should work!

If you don't want to install nbsphinx, you can just copy the relevant code to your own codebase.
I'm not sure if that makes sense, but I could also try to refactor this functionality into its own Sphinx extension ...?

I do not understand how this has not been corrected yet

Well, I don't think this is a bug, so I guess it will never be "corrected".

where I must change to " refdomain='std' ". In conf.py?

No. I was talking about the case if you take my code. You would have to change it there. And this is only relevant for Sphinx 2.0, which will be released in the far-ish future.

[lrmoreno007]

I tried to install it on readthedocs without success, could you help me do it? Thanks in advance.

[mgeier]

@lrmoreno007 Did you follow https://nbsphinx.readthedocs.io/en/latest/usage.html#Automatic-Creation-of-HTML-and-PDF-output-on-readthedocs.org?

Does it work locally?

[lrmoreno007]

Yes I follow the instructions:

• Add in requeriments.txt

ipykernel
nbsphinx

This compile OK in ReadTheDocs

• But when add in conf.py:

extensions = [nbsphinx]

I get this error:

Running Sphinx v1.7.4

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/esp8266-arduino-spanish/envs/latest/local/lib/python2.7/site-packages/sphinx/cmdline.py", line 303, in main
    args.warningiserror, args.tags, args.verbosity, args.jobs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/esp8266-arduino-spanish/envs/latest/local/lib/python2.7/site-packages/sphinx/application.py", line 163, in __init__
    confoverrides or {}, self.tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/esp8266-arduino-spanish/envs/latest/local/lib/python2.7/site-packages/sphinx/config.py", line 167, in __init__
    raise ConfigError(CONFIG_ERROR % traceback.format_exc())
ConfigError: There is a programable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/esp8266-arduino-spanish/envs/latest/local/lib/python2.7/site-packages/sphinx/config.py", line 161, in __init__
    execfile_(filename, config)
  File "/home/docs/checkouts/readthedocs.org/user_builds/esp8266-arduino-spanish/envs/latest/local/lib/python2.7/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/esp8266-arduino-spanish/envs/latest/local/lib/python2.7/site-packages/six.py", line 709, in exec_
    exec("""exec _code_ in _globs_, _locs_""")
  File "<string>", line 1, in <module>
  File "conf.py", line 33, in <module>
    extensions = [nbsphinx]
NameError: name 'nbsphinx' is not defined


Configuration error:
There is a programable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/esp8266-arduino-spanish/envs/latest/local/lib/python2.7/site-packages/sphinx/config.py", line 161, in __init__
    execfile_(filename, config)
  File "/home/docs/checkouts/readthedocs.org/user_builds/esp8266-arduino-spanish/envs/latest/local/lib/python2.7/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/esp8266-arduino-spanish/envs/latest/local/lib/python2.7/site-packages/six.py", line 709, in exec_
    exec("""exec _code_ in _globs_, _locs_""")
  File "<string>", line 1, in <module>
  File "conf.py", line 33, in <module>
    extensions = [nbsphinx]
NameError: name 'nbsphinx' is not defined

I'm not working locally, I'm working in this repo: https://github.com/lrmoreno007/ESP8266-Arduino-Spanish
When everything work fine I'll pull in the original repo (this repo).

[lrmoreno007]

Ok, now it has been installed I made a mistake by not putting the quotes:
extensions = ['nbsphinx']

I will try now and I will comment.

[lrmoreno007]

I must work now with: ":ref:" ?

[lrmoreno007]

WOW!!!! It's partially working!!

Work fine with something like this:

`Software Serial <libraries.rst#softwareserial>`__

OK ---> https://github.com/lrmoreno007/ESP8266-Arduino-Spanish/blob/master/doc/reference.rst#serial
OK ---> https://esp8266-arduino-spanish.readthedocs.io/es/latest/reference.html#serial

But don't work with:

`Modulo Generico ESP8266 <../boards.rst#generic-esp8266-modules>`__

OK ---> https://github.com/lrmoreno007/ESP8266-Arduino-Spanish/blob/master/doc/faq/a01-espcomm_sync-failed.rst#introducci%C3%B3n
NOK ---> https://esp8266-arduino-spanish.readthedocs.io/es/latest/faq/a01-espcomm_sync-failed.html#introduccion

[mgeier]

The second one doesn't work because there is no section named "Generic ESP8266 Modules".

It should work if you try this:

 `Modulo Generico ESP8266 <../boards.rst#modulo-generico-esp8266>`__

[lrmoreno007]

OMG!!! You are the boss!! I was determined that it was a problem with "../" and had tried a thousand ways.

Now everything work fine. Thank you very much for your help, without you I could not have solved it.

[mgeier]

I'm glad I could help! Have fun!

[devyte]

Referenced PR isn't merged yet.

[devyte]

Merged now.

[lrmoreno007]

This work like a charm! Close the issue.

Regards.