wish: Make anchors visible in Alectryon's webpage output

[erikmd]

Hi @cpitclaudel, I don't know if this was already in your roadmap :)

It appears the webpage output already contains some anchors <div id="key-words" class="section">, hence the suggestion:

it would be awesome if these anchors could be directly "exposed" to the user, e.g. similarly to how GitHub renders Markdown files:

[cpitclaudel]

That's a great idea. I think it would require a change to Docutils html writer, specifically the visit_title function in writers/_html_base.py. Could you open a feature request on the docutils tracker?

(Note that Sphinx already has this feature — see e.g. in Coq's reference manual)

[erikmd]

Hi @cpitclaudel, OK thanks for your feedback! So I'm adding your suggestion to my backlog :)

[erikmd]

FYI @cpitclaudel, I opened this ticket:

https://sourceforge.net/p/docutils/feature-requests/77

[erikmd]

Hi @cpitclaudel, I got a response in https://sourceforge.net/p/docutils/feature-requests/77/#d092 (asking quite rightly for a minimal complete example using docutils). But I'm much less docutils-savvy than you; so would it be feasible for you to prepare one such example? (And if you don't have a Sourceforge account, I could obviously post your example if need be.)

[erikmd]

Also I am not 100% sure, but it seems docutils already has some code to output <h2><a href="#keywords">…</a></h2> code: see https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/writers/_html_base.py#l1561

        self.body.append(
              self.starttag(node, 'h%s' % h_level, '', **atts))
        atts = {}
        if node.hasattr('refid'):
            atts['class'] = 'toc-backref'
            atts['href'] = '#' + node['refid']
        if atts:
            self.body.append(self.starttag({}, 'a', '', **atts))
            close_tag = '</a></h%s>\n' % (h_level)
        else:
            close_tag = '</h%s>\n' % (h_level)

WDYT?

[cpitclaudel]

Also I am not 100% sure, but it seems docutils already has some code to output

…

It inserts an href (a link back to the table of contents), not an anchor (something that you can link to). (I could be wrong)

[cpitclaudel]

But I'm much less docutils-savvy than you; so would it be feasible for you to prepare one such example?

Done

[erikmd]

FTR: the upstream ticket has been closed as a duplicate of https://sourceforge.net/p/docutils/feature-requests/28/

[erikmd]

FYI, the feature wish in the docutils tracker has just been implemented! :tada:

(cf. this commit in trunk)

I won't be able to test it before several days though, but just wanted to let you know :smiley:

[anton-trunov]

@erikmd Awesome news! I tried the trunk version of docutil: I downloaded the latest snapshot, unzipped it and ran pip3 install ./ from within the unpacked folder. I then tried building my Coq files like so:

alectryon --expect-unexpected --frontend coq+rst --backend webpage lectures/lecture01.v -o lectures/lecture01.html

but I got the following error

AttributeError: 'Values' object has no attribute 'xml_declaration'
Exiting due to error.  Use "--traceback" to diagnose.
Please report errors to <docutils-users@lists.sf.net>.
Include "--traceback" output, Docutils version (0.18b.dev [release]),
Python version (3.9.5), your OS type & version, and the
command line used.

[cpitclaudel]

Can you pass --traceback to show the full error trace?

[anton-trunov]

Can you pass --traceback to show the full error trace?

Here you go:

$ alectryon --traceback --expect-unexpected --frontend coq+rst --backend webpage lectures/lecture01.v -o lectures/lecture01.html
Traceback (most recent call last):
  File "/usr/local/bin/alectryon", line 8, in <module>
    sys.exit(main())
  File "/usr/local/lib/python3.9/site-packages/alectryon/cli.py", line 643, in main
    process_pipelines(args)
  File "/usr/local/lib/python3.9/site-packages/alectryon/cli.py", line 632, in process_pipelines
    state = call_pipeline_step(step, state, ctx)
  File "/usr/local/lib/python3.9/site-packages/alectryon/cli.py", line 597, in call_pipeline_step
    return step(state, **{p: ctx[p] for p in params})
  File "/usr/local/lib/python3.9/site-packages/alectryon/cli.py", line 111, in gen_rstcoq_html
    return _gen_docutils_html(coq, fpath, webpage_style,
  File "/usr/local/lib/python3.9/site-packages/alectryon/cli.py", line 97, in _gen_docutils_html
    return publish_string(
  File "/usr/local/lib/python3.9/site-packages/docutils/core.py", line 407, in publish_string
    output, pub = publish_programmatically(
  File "/usr/local/lib/python3.9/site-packages/docutils/core.py", line 665, in publish_programmatically
    output = pub.publish(enable_exit_status=enable_exit_status)
  File "/usr/local/lib/python3.9/site-packages/docutils/core.py", line 220, in publish
    output = self.writer.write(self.document, self.destination)
  File "/usr/local/lib/python3.9/site-packages/docutils/writers/__init__.py", line 78, in write
    self.translate()
  File "/usr/local/lib/python3.9/site-packages/docutils/writers/_html_base.py", line 163, in translate
    self.visitor = visitor = self.translator_class(self.document)
  File "/usr/local/lib/python3.9/site-packages/alectryon/docutils.py", line 543, in __init__
    super().__init__(document)
  File "/usr/local/lib/python3.9/site-packages/docutils/writers/_html_base.py", line 301, in __init__
    if settings.xml_declaration:
AttributeError: 'Values' object has no attribute 'xml_declaration'

[cpitclaudel]

Thanks, should be fixed now. But note that Sphinx isn't compatible yet with that version of docutils.

[cpitclaudel]

Looks like this feature has made it into docutils, so we're all set :) Feel free to reopen if you run into issue using this with docutils.