Skip to content

Latest commit

 

History

History
440 lines (328 loc) · 18 KB

README.asciidoc

File metadata and controls

440 lines (328 loc) · 18 KB
Raw

Doc Browser is an API documentation browser with support for DevDocs, Dash and Hoogle, written in Haskell and QML.

The GUI looks like this:

Main Interface

This one is the interface for Hoogle.

This one is the interface for PyTorch.

Table of Contents

Features

  • Native desktop application

  • Works offline

  • Near real-time fuzzy search

  • Easy-to-type shortcuts

  • DevDocs support

  • Dash support (incomplete)

  • Hoogle integration

  • Customizable

  • HTTP interfaces

  • Neovim integration. Editor integration is just a HTTP request away

Current Status

  • The main GUI is suitable for daily use

  • Docset management is usable, but needs polishing

  • Packaging for OSes other than Arch Linux need to be added

  • I use this application every day and happy with it

Contributions Are Welcome

Several other features are planned but I haven’t got the time to implement or improve them, including: (in no particular order)

  1. Packaging for various Linux distributions

  2. Add "Back" and "Forward" navigation button to the GUI (preferably to the tab bar), like the ones in the web browsers

  3. Better support for Dash docsets (the current support is incomplete and hacky)

  4. Better support for Haskell docs (eg. support for individual package)

  5. Add a GUI to manage the docsets (including the ability to auto update the installed docsets)

  6. Integration with diigo, or send the selection to a note service, like cherrytree or Evernote

If you wish to contribute to feature 3, 4 and 5, please do contact me via Github issue before doing it.

Installation

Arch Linux

There is a PKGBUILD available on AUR.

Other Linux Distros

You can build this application from source, which isn’t a pleasant experience. Packaging for popular OSes/package managers are welcome.

Follow these steps to install from source:

  1. This application uses Qt 5, make sure you have it installed. You also need QtWebEngine, install it if it doesn’t come with your Qt installation.

  2. Install the Haskell tool stack.

  3. The build process depends on several executables: c2hs, alex and happy, you can either install it using your package manager, or use the instruction given below.

  4. Install other dependencies mentioned in the depends section in this file, the package name for your package manager may be different with the provided one. You can either install them now, or later in a trial-and-error manner. You don’t need to install mathjax if you don’t intend to use Hoogle.

Finally, run these commands in the shell to build and install the application:

git clone 'https://github.com/qwfy/doc-browser.git'
cd doc-browser

# optionally, install these executables if not already installed:
# stack install c2hs
# stack install alex
# stack install happy

# build and install this application, this will take a while
# if this step fails, then you probably missed some dependencies,
# your can examine the error message to see which dependencies are missing
stack install

echo "binary installed to $(stack path --local-bin)"

If you have trouble building this application, you can:

  • Is it a dependency problem?

  • Does this page help? Especially the Requirements and Installation section.

  • Open an issue.

Optionally, install the executable xsel or xclip for the Y shortcut (copy the selected match to clipboard) to work.

Optionally, install the executable xdg-open (provided by package xdg-utils on Arch Linux) for the Ctrl+/ shortcut (send query to Google) to work.

Optionally, generate a completion script for your shell with:

# completion will be available in a new shell
doc-browser --bash-completion-script `which doc-browser` > /etc/bash_completion.d/doc-browser.bash

# or source them manually:
source <(doc-browser --bash-completion-script `which doc-browser`)

# for Zsh and Fish, there is:
# --zsh-completion-script
# --fish-completion-script

Install DevDocs' Docset

To install DevDocs' docset, invoke:

doc-browser --install-devdocs DOC COLLECTION==VERSION ..

# e.g.
#   doc-browser --install-devdocs python Python==2.7.13
# will install both the latest version of Python 3.x and Python 2.7.13

# use
#   doc-browser --list-remote-devdocs
# to query available docsets and versions

This will download docsets from devdocs.io, and install them to XDG_CONFIG/doc-browser/DevDocs.

Install Dash’s Docset

To install Dash’s docset, invoke:

doc-browser --install-dash COLLECTION ..

# e.g.
#   doc-browser --install-dash Erlang
# will install the Erlang docset

# use
#   doc-browser --list-remote-dash
# to query available docsets

# This will download docsets from kapeli.com, and install them to `XDG_CONFIG/doc-browser/Dash`.

# to install from a locally built archive,
# or those in https://github.com/Kapeli/Dash-User-Contributions,
# use:

doc-browser --install-dash COLLECTION --local-archive ABSOLUTE_PATH_TO_DOCSET_TGZ --version VERSION

# e.g.
#   doc-browser --install-dash PyTorch --local-archive $(pwd)/PyTorch.tgz --version 1.4.0
# will install the docset for PyTorch, version 1.4.0
# where PyTorch.tgz is generated according to:
# https://github.com/Kapeli/Dash-User-Contributions

Enable Hoogle Support

To support Hoogle, this application creates a Hoogle database from a documentation archive, which can be done by these steps:

  1. Find out which documentation archive you want to use. The Hoogle support is tested on archives provided by Stackage, like this one, which can be found at: https://www.stackage.org/lts-10.8. You can use other archives as well, as long as the unpacked archive can be read by hoogle generate --local=dir_to_unpacked_archive, but this is untested. NOTE that stackage no longer provides download links for these kinds of archives, (see commercialhaskell/stackage#4098), so you have to generate the archive yourself.

  2. Invoke the following installation command, this will unpack the archive to XDG_CONFIG/doc-browser/Hoogle/COLLECTION, and creates a Hoogle database XDG_CONFIG/doc-browser/Hoogle/COLLECTION.hoo for it, (doc-browser’s Hoogle doesn’t interfere with your system Hoogle in any way):

doc-browser --install-hoogle URL COLLECTION
# e.g. doc-browser --install-hoogle 'https://s3.amazonaws.com/haddock.stackage.org/lts-10.8/bundle.tar.xz' lts-10.8
#
# URL is where to read the archive.
# It can also be a local file,
# which I suggest you to use if you have a bad network connection,
# since the download function included in this program is pretty savage at this stage.
#
# See `doc-browser --help` for more
#
# Don't panic if you see a lot of lines that look like this
# at the begining and the ending of the generation
# (for the above lts-10.8, there are 43 of these):
#
# temporarily relocate x to x.__co.aixon.docbrowser-tempfile__, for x in:
# /home/user/.config/doc-browser/Hoogle/lts-10.8/prologue.txt
# ...
# move x.__co.aixon.docbrowser-tempfile__ back to x, for x in:
# /home/user/.config/doc-browser/Hoogle/lts-10.8/prologue.txt
# ...
#
# These are necessary to work around a Hoogle issue.

  1. Prefix or suffix a search with "/hh" to query Hoogle, like this: /hh[a]→Int→[a]. Multiple databases are also supported, you need to add a command to specify which database you want to access to, see the Configuration section for instructions.

Start the Application

If you installed the application from AUR, you can either start it with the shipped .desktop file, or with:

doc-browser

If you installed from source, start it with:

doc-browser

# if you see any errors, it's probably due to the missing of dependencies

You can also start it with doc-browser.desktop, found in the root of this repository. Icon is available if you copy icon.svg to a location such as /usr/share/icons/doc-browser.svg.

Offline Support

The documentation files themselves are downloaded to your disk when doc-browser --install-devdocs, doc-browser --install-dash or doc-browser --install-hoogle is invoked, however, to display the documentation, some additional Cascading Style Sh*t or JavaScript files are needed, some of these are not packaged with the documentation files.

DevDocs

To make DevDocs' docsets work fully offline:

  • Start the application after doc-browser --install-devdocs

  • Search for anything, and open any match

  • When the tab is opened and the documentation is correctly displayed, all necessary files are cached, DevDocs' docsets work offline now

Dash

Dash’s docset works offline out of the box.

Hoogle

If a MathJax distribution is found at /usr/share/mathjax (configurable), then the Hoogle documentations will work offline. (If you installed from AUR, you already have it.)

GUI

  • When the application starts, you will see a blank screen, you can start typing to search.

  • Prefix or suffix a search string with "/py", (e.g. "/pyabspath", "abspath/py"), will limit the search to the Python docset provided by DevDocs, more commands are available, see below.

  • Number of tabs will peak at 10, open one more tab will close the left-most one.

  • Various keyboard shortcuts are available, see below.

Commands

These commands are provided by default, you can customize them by following the instructions in the Configuration section.

Command Effect

py

Limit search to DevDocs' Python 3.x

p2

Limit search to DevDocs' Python 2.x

tf

Limit search to DevDocs' TensorFlow

np

Limit search to DevDocs' NumPy

pd

Limit search to DevDocs' pandas

mp

Limit search to DevDocs' Matplotlib

go

Limit search to DevDocs' Go

hs

Limit search to DevDocs' Haskell

pg

Limit search to DevDocs' PostgreSQL

sl

Limit search to DevDocs' SQLite

th

Limit search to Dash’s PyTorch

rs

Limit search to Dash’s Rust

er

Limit search to Dash’s Erlang

sp

Limit search to Dash’s SciPy

hh

Perform search with Hoogle

Shortcuts

Key Effect Comment

/

focus the search box

Ctrl+I

focus and clear the search box, but keep the command, if any

e.g. before: "/pyfoo"; after: "/py"

Enter or Down

accept query and select the first match

when in the search box

ASDFWERTC

open match 1-9

G+ASDFWERTC

open match 10-18

V+ASDFWERTC

open match 19-27

J

select the next match

K

select the previous match

Enter

open the selected match

when the selected item has focus

Tab or Down

select the next match

when the selected item has focus

Shift+Tab or Up

select the previous match

when the selected item has focus

1234567890

go to the corresponding tab

Alt+L

go to the next tab

Alt+H

go to the previous tab

Ctrl+W

close the current tab

Y

copy the selected match to clipboard

need executable xsel or xclip

M

copy the module of the selected match to clipboard

only for Hoogle. need executable xsel or xclip

P

copy the package of the selected match to clipboard

only for Hoogle. need executable xsel or xclip

Ctrl+/

send query to Google

e.g. Ctrl+/ on "/pyfoo" will search Google for "Python foo"; need executable xdg-open

Ctrl+F

open or focus page search

Alt+N

find next in page search

Alt+P

find previous in page search

Esc

close page search

when in search box

Depending on your platform, Ctrl+U can be used to clear the input box, just like in readline.

Configuration

Create the file XDG_CONFIG/doc-browser/config.yaml and edit it.

The file is in YAML format, configurable keys and documentations can be found at:

  • doc-browser --print-default-config

  • or config.yaml in the root of the source repository

HTTP Interface

You can interact with this application using HTTP requests.

API documentation can be found at:

Speed

As can be seen from the below (slighly outdated) benchmark, it takes less than 50ms to search through 39,499 entries.

Prof

Credits and License

This application is written by incomplete@aixon.co, and licensed under MPL-2.0.

You can use the icon.svg in the root of this repository as the icon of this application. Permission is needed if you plan to use it for other purposes.

Many thanks to Thibaut Courouble and other contributors of DevDocs, without their work, this application wouldn’t be possible:

  • This application ships with icons collected by DevDocs.

  • This application uses docsets, along with the corresponding style sheets, produced by DevDocs.

Many thanks to Neil Mitchell for the great Hoogle. The Hoogle support receives helps from him. This application also ships with a little code from the Hoogle project, the modified code is licensed under the BSD license.

Many thanks to Bogdan Popescu for allowing me to use Dash’s docset. This application also ships with icons from the Dash-iOS project. If you are using Mac, please consider Dash.

Known Problems and Solutions

Problem: On KDE, Ctrl+/ is taking too long to open the browser.

Solution: This application uses xdg-open to open the browser. Try this workaround.

Problem: The font in the documentation is too big or too small.

Solution: Tweak the configuration WebEngineZoomFactor, see the Configuration section for instruction.

Problem: HTTP summon interface doesn’t bring the window to front

Solution: Try the section Additional settings for Linux described in here.

Problem: (China users only) Installation of docsets hangs/open documentation shows blank screen.

Solution: devdocs.io or cloudflare.com is blocked by GFW, please use a VPN.

Problem: Install/uninstall some Dash docsets reports error.

Solution: If a docset has / in its name or version, (many Dash docsets do), the installation or uninstallation may not work. This problem is known from the begining, it’s just that I haven’t got time to fix it properly (without introducing un-upgradable changes). Solution: wait for me to fix it :(

FAQ

Q: Why does this application display at most 27 matches?

A: If your desired match is not in the top 27 matches, then there is probably something wrong with the search algorithm.

Q: Why does this application display at most 10 tabs?

A: If too many tabs are displayed, the tab title would be hard to see on many monitors. Instead of wanting more tabs, try open another instance of this application. The number of maximum tabs will be configurable in future versions, so you can benefit from a large monitor.

Tips

  • Typically, you can omit characters such as '_' (those require you holding Shift to type) from your query string, your pinky might thank you for that.