dronekit/sphinx_3dr_theme

Sphinx 3DR Theme based on sphinx_rdt_theme

sphinx_3dr_theme's Issues

Add Page Bug link in footer

Lets make it easier for people to report bugs against pages by adding a Page Bug link to the footer. When clicked the link should open a github issue with the subject and body appropriately seeded with the page name and URL.

The will require a config setting in theme so we can enter the target github repo for issues.

It can be done using templating.

You can see an example of what I mean in the Page bug link at the bottom of this page

CSS does not provide CSS to support restructuredtext notes, tips, warnings, hints

The ability to add notes, hints, tips, warnings is very useful. Most themes support this CSS. Can we get it added please. See http://udig.refractions.net/files/docs/latest/user/docguide/sphinxSyntax.html#notes-and-warnings

Add support for sphinx directives versionadded and deprecated

versionadded can be green or yellow - a type of note. deprecated should be a type of warning. I use versionadded in the API Reference for the gimbal dronekit/dronekit-python#498 . I don't use deprecated because this needs to stand out ... but I will if you add support for it :-)

No obvious link in Python docs back to the Python home page

If you navigate to any sidebar link, then there is no obvious UI option to go back to the home page/table of contents.

There is actually an option - clicking the top header bar option for Android/Python - but this doesn't feel like obvious navigation to me. Adding a "Table of Contents" link at the bottom of the glossary or a "Home" at the top might help.

More professional feel for API reference

Original posted here dronekit/dronekit-python#310 (comment)

The API reference page for dronekit python is hard to follow and looks very foreign to a programmer. I have stopped going there because it is easier to look at the source code then find what I am looking for on that page.

I suggest we try to match the format of current python API documentation. This will make the experience more familiar and easy to comprehend.

Here are a few python examples:
http://docs.opencv.org/modules/highgui/doc/reading_and_writing_images_and_video.html
https://docs.python.org/2/library/logging.html

Notable characteristics:
-Header/page break for every function(i.e. distinguishable dividers)
-Bold function names
-shows how the function is called in one line
-Lists and describes parameters
-Plenty of white space!
-Class name is listed in front of function name(when applicable)

Non essentials:
-Basic color scheme. Not too crazy
-Show deprecated methods

Other examples:
-Java docs has a very clean, extensible layout. I have never seen it used with python but is a great resource for an API

Links take you below the target mk2

I use explicit references to link to documents. This allows me to link to headings, and to documents, even if the documents move around.

The links are taking me below the target. For example, there is an anchor at the top of the page: http://python.dronekit.io/quick_start.html#quick-start

I get this:

I want this:

Other "top of page" example is http://python.dronekit.io/guide/getting_started.html#get-started

Here is an in-page heading link to a heading: http://python.dronekit.io/quick_start.html#vagrant-sitl-from-full-image - see the heading is off-screen:

Useless scroll bars surrounding java code

See here for an example. This doesn't seem to happen to .. codeblock:: xml but it does happen to .. codeblock:: java

Sidebar should open with "page TOC" for current document

Currently the sidebar TOC shows displays page titles only. When a page is opened, the toc should expand at that point to include the contents for the page itself.

This is next step from #17.

No way to differentiate code items and code links

Inline code items (marked up with double backticks) and code references (links, marked up with :py:class:whatever) appear the same. A working link code link should be highlighted differently.

Add a vagrantfile to make it easy to get up and running with this theme

I can't test changes to this properly because I cant get the build to run (using Vagrant).

I tried vagrantfile below in root, but can't get it to install all dependencies. Have assigned to the expert - that's you @mrpollo !

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure(2) do |config|
    config.vm.box = "ubuntu/trusty64"

    config.vm.provision "shell", inline: <<-SHELL
        apt-get -y update
        echo "[Sphinx 3DR Theme]: Installing build essentials"
        apt-get -y install build-essential
        echo "[Sphinx 3DR Theme]: Installing Python Devel"
        apt-get -y install python-dev
        echo "[Sphinx 3DR Theme]: Installing pip ..."
        apt-get -y install python-pip
        easy_install -U pip
        echo "[Sphinx 3DR Theme]: Installing Sphinx ... "
        pip install sphinx
        echo "[Sphinx 3DR Theme]: Installing NPM ... "
        apt-get -y install npm
        echo "[Sphinx 3DR Theme]: Installing Bundler ... "
        gem install bundler
        echo "[Sphinx 3DR Theme]: Installing Bower ... "
        npm install -g bower
        echo "[Sphinx 3DR Theme]: Installing Grunt-cli ... "
        npm install -g grunt-cli
        echo "[Sphinx 3DR Theme]: Installing NPM requirements  ... "        
        npm install
        echo "[Sphinx 3DR Theme]: Installing Bower requirements  ... "  
        bower install
        echo "[Sphinx 3DR Theme]: Building"
        grunt build
    SHELL
end

Improved expandable multi-level sidebar

Previously raised in wrong repo. I am reopening here because we have hit the limitations of the current sidebar.

Make the sidebar expandable like the one this site.

What this allows that we don't have now:

• Full TOC is displayed for current page in the sidebar.
• Current page is highlighted in sidebar, providing context
• Deeper nesting - at the moment we really only have 2 levels, and we really need 3 or 4.
• Expansion of the tree to the current point.

In summary, this displays a more TOC detail for the current page, while still giving the overview/context of the page within the hierarchy. This is a much better sidebar if you have a bigger documentation set, with some levels of nesting.

Bullets have some issues

This still has some issues following #5 being closed.

1. Odd misalignment - more visible magnified

1. The next lines are indented back which to my mind looks really odd. Shouldn't subsequent lines align with the first line?

Rendering of code is not very attractive or useable

The CSS for the autogenerated class documentation is not very useable - http://python.dronekit.io/automodule.html

Consider the example below:

• It is hard to visually distinguish the second class
• it is hard to work out which functions belong to which class, and functions are just as easy to see as classes so "hide" them
• the parameters (and returns) are more bold than classes classes, hence distracting.

The solution is probably to make classes a little more prominent. Indent any description text for them. Further indent any associated attributes, documentation, functions etc. They might perhaps be a little larger, and function parameters a little smaller.

In addition there is not enough space after tables:

Spacing before header

This is what the docs look like right now:

This is what it looks like when I make the docs using an old version of this same theme:

Indented bullet spacing not quite right

Single level list looks OK (though arguably the space to first bullet could be a bit reduced).

With indented bullet, the spacing isn't quite right - I think the space before the indented bullet should be reduced, and possibly a bit more after. In addition, note how the spacing between the top level bullets is also much bigger than in the example screenshot above.

This is a "mockup" of how it might look if improved:

See example here - note, this is a temporary link, hosted on dropbox.

3DR Logo missing from navbar on IE/Firefox #39

The "3DR" logo is displayed on top left of navbar on Chrome, but not Firefox or IE (for chrome I tried on a fresh browser, so I think it is not a caching issue).

See dronekit/dronekit-python#39 (closed, because I am opening here) for diagrams

Links to references take you below the target

Consider this link to the Vehicle.flush method (on my dropbox).

It takes you here (just below the heading):

When it should take you here (just above the heading):

A version of the autodocs with these links (for manual testing) will be available when this changelist is merged.
dronekit/dronekit-python#58

In the meantime you can easily test just by selecting links from the genindex on the live site.

How is this used in a Sphinx project?

I expected to be able to use this in the normal way:

1. Get the theme
   sudo pip install sphinx_3dr_theme
2. In the conf.py
   import sphinx_3dr_theme
   html_theme = 'sphinx_3dr_theme'
   html_theme_path = [sphinx_3dr_theme.get_html_theme_path()]

However running the drone-kit python docs (e.g. this conf.py) it fails due to missing conf.py in your theme (and yes, this does appear to be missing from the pip installation.

What is the correct way to use this with https://github.com/diydrones/dronekit-python ?

Add mechanism to easily access the sidebar TOC menu

For some large topics, like Getting Started the navigation scrolls out of view. If you want to access it then you have to do a lot of scrolling up to get back to it.

The requirement is to create a mechanism to make it easy to get to the sidebar TOC again. Some ideas:

• A "jump to top" button that is visible when the sidebar toc is off-screen and you are scrolling up
• The sidebar will only scroll as far as the bottom of its content, irrespective of what the main content does (always on-screen). Scrolling up in content also scrolls up the sidebar.
• Other?

UPdate the PIP

Can you please create and upload a new PIP then at least I could see what my changes look like before submitting them.

Heading 2 level has a huge unnecessary 70px padding-top

This spaces the sections apart far too much, and should be removed