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

Customized and bootstrap-ifyed HTMLTranslator #92

Open
wants to merge 21 commits into
base: master
Choose a base branch
from
Open

Customized and bootstrap-ifyed HTMLTranslator #92

wants to merge 21 commits into from

Conversation

torbjoernk
Copy link
Contributor

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

Review on Reviewable

attention, see also and error directives

Signed-off-by: Torbjörn Klatt <[email protected]>
adding an example module to show of sphinx.ext.autodoc features

Signed-off-by: Torbjörn Klatt <[email protected]>
Most sphinx and docutils directives are implemented to produce
bootstrap-aware html.
Some stuff needs some tweaking and cleanup (it's mostly a little too
hacky).

Signed-off-by: Torbjörn Klatt <[email protected]>
Notes and Examples can be rendered as admonitions automatically when
using the Napoleon docstring parser.

Signed-off-by: Torbjörn Klatt <[email protected]>
also annotation style in member signatures

Signed-off-by: Torbjörn Klatt <[email protected]>
Signed-off-by: Torbjörn Klatt <[email protected]>
Signed-off-by: Torbjörn Klatt <[email protected]>
remove span around them to not screw toctrees

Signed-off-by: Torbjörn Klatt <[email protected]>
Signed-off-by: Torbjörn Klatt <[email protected]>
is now a static navbar at the bottom

Signed-off-by: Torbjörn Klatt <[email protected]>
@torbjoernk
Copy link
Contributor Author

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
Copy link
Owner

@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!

and some minor style tweaks for object description signature annotations

Signed-off-by: Torbjörn Klatt <[email protected]>
the most ugliest styling errors/flaws with BS2 should be fixed now

Signed-off-by: Torbjörn Klatt <[email protected]>
@torbjoernk
Copy link
Contributor Author

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

@russell
Copy link
Collaborator

russell commented Mar 20, 2014

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
Copy link
Contributor Author

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
Copy link
Collaborator

russell commented Mar 20, 2014

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
Copy link
Contributor Author

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
Copy link
Owner

@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
Copy link
Collaborator

russell commented Jun 12, 2014

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
Copy link
Owner

@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
Copy link
Collaborator

russell commented Jun 12, 2014

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

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

Successfully merging this pull request may close these issues.

3 participants