https://github.com/qwfy/doc-browser

A documentation browser with support for DevDocs, Dash and Hoogle, written in Haskell and QML
https://github.com/qwfy/doc-browser

api-documentation dash devdocs developer-tools documentation-tool hoogle

Last synced: 3 months ago
JSON representation

A documentation browser with support for DevDocs, Dash and Hoogle, written in Haskell and QML

Host: GitHub
URL: https://github.com/qwfy/doc-browser
Owner: qwfy
License: mpl-2.0
Created: 2018-02-23T14:22:53.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2021-10-09T05:11:16.000Z (over 3 years ago)
Last Synced: 2023-11-07T18:59:18.153Z (over 1 year ago)
Topics: api-documentation, dash, devdocs, developer-tools, documentation-tool, hoogle
Language: Jupyter Notebook
Homepage:
Size: 6.77 MB
Stars: 129
Watchers: 10
Forks: 10
Open Issues: 3
Metadata Files:
- Readme: README.asciidoc
- License: LICENSE

Awesome Lists containing this project

README

:toc: macro
:experimental:

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

The GUI looks like this:

image:asset/interface-annotated.png[Main Interface]

link:asset/interface-hoogle.png[This one] is the interface for Hoogle.

link:asset/interface-torch.png[This one] is the interface for PyTorch.

toc::[]

== Features

* Native desktop application
* Works offline
* link:#speed[Near real-time] fuzzy search
* Easy-to-type shortcuts
* DevDocs support
* Dash support (incomplete)
* Hoogle integration
* Customizable
* link:#http-interface[HTTP interfaces]
* link:https://github.com/qwfy/doc-browser-nvim[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 https://aur.archlinux.org/packages/doc-browser-git/[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 http://qt-project.org/[Qt 5], make sure you
have it installed. You also need https://wiki.qt.io/QtWebEngine[QtWebEngine],
install it if it doesn't come with your Qt installation.
2. Install the Haskell tool
https://docs.haskellstack.org/en/stable/install_and_upgrade/[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
https://github.com/qwfy/doc-browser/blob/master/aur/PKGBUILD[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:

[source,bash]
----
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 http://www.gekkou.co.uk/software/hsqml/[this page] help?
Especially the _Requirements_ and _Installation_ section.
* Open an issue.

Optionally, install the executable `xsel` or `xclip` for the kbd:[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 kbd:[Ctrl+/] shortcut (send query to
Google) to work.

Optionally, generate a completion script for your shell with:

[source,bash]
----
# 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:

[source,bash]
----
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:

[source,bash]
----
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
https://www.stackage.org[Stackage], like
https://s3.amazonaws.com/haddock.stackage.org/lts-10.8/bundle.tar.xz[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 https://github.com/commercialhaskell/stackage/issues/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):

[source,bash]
----
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.
----

3. 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
link:#configuration[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:

[source,bash]
----
doc-browser
----

If you installed from source, start it with:

[source,bash]
----
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 link:#configuration[Configuration] section.

[cols=",",options="header",]
|===
| 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

Depending on your platform, kbd:[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:

* https://qwfy.github.io/doc-browser/http-interface.html
* or, `doc-browser --print-api`

== Speed

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

image:prof/compare of speed of several implementations - no edit distance.png[Prof]

== Credits and License

This application is written by [email protected], 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 https://github.com/Thibaut[Thibaut Courouble] and
https://github.com/Thibaut/devdocs/graphs/contributors[other
contributors] of https://github.com/Thibaut/devdocs[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 https://github.com/ndmitchell[Neil Mitchell] for the
great https://github.com/ndmitchell/hoogle[Hoogle]. The Hoogle support
receives https://github.com/qwfy/doc-browser/issues/2[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 https://github.com/Kapeli/Dash-iOS[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
https://kapeli.com/dash[Dash].

== Known Problems and Solutions

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

Solution: This application uses `xdg-open` to open the browser. Try
https://bugs.kde.org/show_bug.cgi?id=364662#c3[this workaround].

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

Solution: Tweak the configuration `WebEngineZoomFactor`, see the
link:#configuration[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
https://kb.froglogic.com/display/KB/Problem+-+Bringing+window+to+foreground+%28Qt%29[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 kbd:[Shift] to type)
from your query string, your pinky might thank you for that.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/qwfy/doc-browser

Awesome Lists containing this project

README