REST / Sphinx의 링크 내부 대체
https://stackoverflow.com/questions/1227037
-
22-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russian문제
Sphinx를 사용하여 다른 서버에 배포 될 웹 서비스를 문서화하고 있습니다. 문서는 사용자가 클릭 할 수있는 URL 예제로 가득 차 있으며 만 작동해야합니다. 내 문제는 호스트, 포트 및 배포 루트가 다르고 모든 배포에 대해 문서를 다시 생성해야한다는 것입니다.
다음과 같은 대체를 정의하려고 시도했습니다.
|base_url|/path
.. |base_url| replace:: http://localhost:8080
그러나 생성 된 HTML은 내가 원하는 것이 아닙니다 (생성 된 링크에 "/path"가 포함되지 않음).
<a href="http://localhost:8080">http://localhost:8080</a>/path
이 문제를 해결하는 방법을 아는 사람이 있습니까?
해결책
Sphinx v1.0의 새로운 것 :
Sphinx.ext.extLinks - 외부 링크를 단축하기위한 마크 업
http://sphinx.pocoo.org/ext/extlinks.html
확장자는 하나의 새로운 구성 값을 추가합니다.
ExtLinks
이 구성 값은 외부 사이트의 사전이어야하며 고유 한 짧은 별칭 이름을 기본 URL 및 접두사에 매핑해야합니다. 예를 들어 위에서 언급 한 문제에 대한 별칭을 만들려면 추가합니다.
extlinks = {'issue':
('http://bitbucket.org/birkenfeld/sphinx/issue/%s', 'issue ')}
이제 별명 이름을 새로운 역할로 사용할 수 있습니다. :issue:`123`. 그런 다음 링크를 삽입합니다 http://bitbucket.org/birkenfeld/sphinx/issue/123. 보시다시피, 역할에 주어진 목표는 대신 기본 URL로 대체됩니다. %s.
링크 캡션은 튜플의 두 번째 항목 인 접두사에 따라 다릅니다.
접두사가 없으면 링크 캡션이 전체 URL입니다. 접두사가 빈 문자열 인 경우 링크 캡션은 역할 컨텐츠에 주어진 부분 URL입니다 (이 경우 123) 접두사가 비어 있지 않은 문자열 인 경우 링크 캡션은 부분 URL입니다. 위의 예에서 링크 캡션은 문제가됩니다. :issue:`this issue <123>`. 이 경우 접두사는 관련이 없습니다.
다른 팁
좋아, 여기 내가 한 방법이있다. 첫 번째, apilinks.py (스핑크스 확장) :
from docutils import nodes, utils
def setup(app):
def api_link_role(role, rawtext, text, lineno, inliner, options={},
content=[]):
ref = app.config.apilinks_base + text
node = nodes.reference(rawtext, utils.unescape(ref), refuri=ref,
**options)
return [node], []
app.add_config_value('apilinks_base', 'http://localhost/', False)
app.add_role('apilink', api_link_role)
지금에 conf.py, 추가하다 'apilinks' 확장자 목록에 'apilinks_base' (그렇지 않으면 기본값이됩니다 'http://localhost/'). 내 파일은 다음과 같습니다.
extensions = ['sphinx.ext.autodoc', 'apilinks']
# lots of other stuff
apilinks_base = 'http://host:88/base/'
용법:
:apilink:`path`
산출:
<a href="http://host:88/base/path">http://host:88/base/path</a>
이미지 대상에서 URL을 대체 해야하는 비슷한 문제가있었습니다. 그만큼 extlinks 이미지 값으로 사용될 때 확장하지 마십시오. :target: 기인하다. 결국 나는 주어진 접두사로 시작하는 URL을 다시 작성하는 사용자 정의 스핑크스 변환을 썼습니다. http://mybase/. 다음은 conf.py에 대한 관련 코드입니다.
from sphinx.transforms import SphinxTransform
class ReplaceMyBase(SphinxTransform):
default_priority = 750
prefix = 'http://mybase/'
def apply(self):
from docutils.nodes import reference, Text
baseref = lambda o: (
isinstance(o, reference) and
o.get('refuri', '').startswith(self.prefix))
basetext = lambda o: (
isinstance(o, Text) and o.startswith(self.prefix))
base = self.config.mybase.rstrip('/') + '/'
for node in self.document.traverse(baseref):
target = node['refuri'].replace(self.prefix, base, 1)
node.replace_attr('refuri', target)
for t in node.traverse(basetext):
t1 = Text(t.replace(self.prefix, base, 1), t.rawsource)
t.parent.replace(t, t1)
return
# end of class
def setup(app):
app.add_config_value('mybase', 'https://en.wikipedia.org/wiki', 'env')
app.add_transform(ReplaceMyBase)
return
이것은 다음 RST 소스를 확장하여 영어 Wikipedia를 가리 킵니다. conf.py를 설정할 때 mybase="https://es.wikipedia.org/wiki" 링크는 스페인 위키를 가리킬 것입니다.
* inline link http://mybase/Helianthus
* `link with text <http://mybase/Helianthus>`_
* `link with separate definition`_
* image link |flowerimage|
.. _link with separate definition: http://mybase/Helianthus
.. |flowerimage| image:: https://upload.wikimedia.org/wikipedia/commons/f/f1/Tournesol.png
:target: http://mybase/Helianthus
