Customized and bootstrap-ifyed HTMLTranslator

[torbjoernk]

I couldn't resist and started writing a custom HTMLTranslator for producing Bootstrap-tailored HTML directly without the need for patching the standard HTML via Javascript.

This is still a work in progress and a couple of things still need to be done. However, I felt like sharing my current work.

ToDos:

• clean-up and fix-up HTML template files especially for navbar and dropdowns.
• further testing and tweaking of ReST directives
• further testing and tweaking of autodoc directives
• BS2 compatibility

[torbjoernk]

I did a couple of further tweaks and also reworked the top navbar and footer. The "Next/Previous Chapter" links are now in a fixed-to-bottom navbar. The source link position now defaults to the footer navbar.

The custom HTML writer still needs some work and love. Currently it's mostly targeted towards the new and upcoming Napoleon parser for Google and Numpy style docstrings (I'm using the latter for my main project at the moment).

I haven't tested any of my changes with Bootstrap version 2.x.

Please, see this PR as a work in progress. Before merging it into the mainline I'll clean all the commits and squash them together.

[ryan-roemer]

@torbjoernk -- Great to see the progress! We're going to need BS2 support, as there is a reasonable contingent of users still on that platform. Oh, and mind throwing the new .py files through the ol' pep8 before the final PR? (We maybe should add a fab pep8 task for doing this programmatically)... THANKS!

[torbjoernk]

Ok. Did some PEP8-ifications and some first adjustments to make it work with BS2.

[russell]

This change is impressive, i didn't know that sphinx even supported custom HTML translators. I just had a quick look and it's much better than using javascript to modify the dom.

So i believe that these are the maining functions that need to be implemented, i started looking into this when i found that the glossary directive wasn't working. I got this list by looking at the methods implemented by sphinx translator that didn't exist in the docutils translator, then comparing that list with your new bootstrap translator methods to see which ones aren't currently implemented.

visit_acks
visit_caution
visit_centered
visit_danger
visit_desc_type
visit_download_reference
visit_glossary
visit_highlightlang
visit_hint
visit_hlist
visit_hlistcol
visit_important
visit_literal_emphasis
visit_literal_strong
visit_production
visit_productionlist
visit_reference
visit_start_of_file
visit_tabular_col_spec
visit_termsep
visit_tip
visit_versionmodified

Beyond that, i'm going to try and render one of my projects up with this. It might be worth trying to render the python.org doc or something like that just to make sure that the formating looks reasonable. I'm worried that it might look too boxy with all the accordian groups.

[torbjoernk]

I'm happy, that someone actually takes up my little contribution.

I guess, the best way to discover unimplemented functions is to just run Sphinx with the custom translator and wait for NotImplemented errors thrown by #unknown_visit.

I understand your concerns about a too boxy look very well. I've just searched for an easy way to reduce the scrollbar for very large pages with a lot of classes and methods documented.
It would be a very nice feature (of Sphinx) to produce a local toctree with classes, methods, functions and attributes as its entries to be displayed on the sidebar (for BS2) or additional dropdown menu (in case of BS3).

Unfortunately, I'm not having any spare time to extend my work with this custom translator but need to get my main work done.

[russell]

So the problem is that it's going to take a bit of time for this to become mature. So perhaps we should keep this feature in a branch for the time being. We will need the translator to support all the methods i mentioned above before we can really consider changing the foundation of the theme. We will also need to expand the example pages to include all of the different node types that are missing.

Yes. the TOC tree code sucks but if i remember correctly it's not possible to change. I will look into it though. We might still need JS to make the TOC into something of value.

@torbjoernk, do you mind if i squash what you've got and pull it onto a branch? I'm happy to do the next itteration and build on what you have done.

@ryan-roemer what do you think?

[torbjoernk]

Please, feel free to do and work with my code as you like. I'll stay tuned and will contribute as much as my time schedule allows.

[ryan-roemer]

@russell -- A long running branch for this case sounds good. Then we can start with a base and have anyone do PRs against that... Maybe also add explicit notes about the branch in the master README.

@torbjoernk -- Thanks for your continued work (as available)! @russell and I are in the same boat "real job"-wise, so we both appreciate what time you can find to help advance the theme further.

[russell]

Right. So i have spent the past couple of months plodding away and this is where i'm at now.

• squashed @torbjoernk's commits into 2 commits.
• added pygments highlighting to source blocks
• removed some python specific annotations to the code (sorry @torbjoernk)
• modified the field printing behaviour, mostly to simplify the code. We have a find_parent function to figure out our current context.
• added some extra testing for ack, glossery, literal types

@torbjoernk I ended up changing the field list areas into pull quotes, it removes one level of the blocks from the interface.

@ryan-roemer provided you don't have a problem with the branch existing within the main repository i'm happy to move it there. I have tested bootstrap 2 functionality, it's OK but there are some improvements that should be made before anyone actually uses it with bootstrap 2.

Here is the lastest commit in the branch 110f294. What a sad commit to stop on, i was hoping for something more impressive. The actual branch is located @russell/sphinx-bootstrap-theme/custom-html-writer

Whats next.

• Better bootstrap 2 support, it should be done if possible with a subclass.
• More examples
• Tests rendering with python.org or some other large project doc.

[ryan-roemer]

@russell -- Thanks for keeping on this and building on @torbjoernk 's work! I'm fine with an ongoing branch in the main repo, and in fact would prefer it there...

[russell]

@ryan-roemer i have pushed the branch to your repo with the branch name feature-custom-html-writer