Skip to content
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

Problem with rendering Sphinx substitutions in HTTPDomain extension #6

Open
bomb-on opened this issue Jan 31, 2017 · 1 comment
Open

Comments

@bomb-on
Copy link

bomb-on commented Jan 31, 2017

@dahlia (or anyone else who can help)
I am trying to use your extension (sphinxcontrib.httpdomain) in my project and I defined my 'routing table' like this:

# conf.py
from sphinx.domains.std import StandardDomain

def setup(app):
    StandardDomain.initial_data['labels']['routingtable'] = (
        'http-routingtable',
        '',
        'HTTP Routing Table')
    StandardDomain.initial_data['anonlabels']['routingtable'] = (
        'http-routingtable',
        '')

I also defined few simple substitutions which I use throughout my docs, e.g.:

# conf.py
rst_epilog = """
.. |mongodb_icon| raw:: html

   <span class="icon-dbs-mongodb"></span>
"""

When I put this substitution in the synopsis directive, it is rendered out on the 'routing table' page as plain text (e.g. |mongodb_icon| instead of <span class="icon-dbs-mongodb"></span>):

# in some .rst file
.. http:post:: /companies/
   :synopsis: Some text whatever |mongodb_icon|

Is it possible to 'force' this page (routing table) to render out my substitutions properly?

@bomb-on
Copy link
Author

bomb-on commented Jan 31, 2017

I tried to play around with a "fix" for this and I found that problem lies in generate(), specifically line 336:

    def generate(self, docnames=None):
        content = {}
        items = ((method, path, info)
            for method, routes in self.domain.routes.iteritems()
            for path, info in routes.iteritems())
        items = sorted(items, key=lambda item: item[1])
        for method, path, info in items:
            entries = content.setdefault(self.grouping_prefix(path), [])
            entries.append([
                method.upper() + ' ' + path, 0, info[0],
                http_resource_anchor(method, path), '', '', info[1]  # info[1] renders out substitution as plain text
            ])
        content = content.items()
        content.sort(key=lambda (k, v): k)
        return (content, True)

What I tried is instead of using info[1] to figure out if there is a substitution defined for this particular string and replace it, something like:

    def generate(self, docnames=None):
        content = {}
        items = ((method, path, info)
                 for method, routes in self.domain.routes.items()
                 for path, info in routes.items())
        items = sorted(items, key=lambda item: item[1])
        for method, path, info in items:
            # check if there are any substitutions machin ones defined in `rst_epilog` and replace them
            substitution = re.search('(\|(.*)\|)', info[1])
            if substitution:
                replacement = re.search(substitution.group(0), self.domain.env.config.rst_epilog)
                if replacement:
                    sub_parsed = self.domain.env.config.rst_epilog.split(substitution.group(0))[1].split('\n')[2].strip()
                    parsed_line = info[1].replace(substitution.group(0), sub_parsed)
            else:
                parsed_line = info[1]
            entries = content.setdefault(self.grouping_prefix(path), [])
            entries.append([
                method.upper() + ' ' + path, 0, info[0],
                http_resource_anchor(method, path),
                '', 'Deprecated' if info[2] else '', parsed_line
            ])
        items = sorted(
            (path, sort_by_method(entries))
            for path, entries in content.items()
        )
        return (items, True)

This does replace the substitution with (in my case) proper HTML - instead of |mongodb_icon|, parsed_line is now <span class="icon-dbs-mongodb"></span>.
However, visiting the "routing table" page wraps this particular string into <em></em> block and therefore I end up with escaped HTML on the page instead of showing the icon itself.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant