Skip to content
This repository has been archived by the owner on Aug 16, 2024. It is now read-only.

Latest commit

 

History

History
165 lines (109 loc) · 6.29 KB

README.md

File metadata and controls

165 lines (109 loc) · 6.29 KB
Raw

doctree: 100% open-source library docs tool for every language

doctree provides first-class library documentation for every language (based on tree-sitter), with symbol search & more. If connected to Sourcegraph, it can automatically surface real-world usage examples.

Try it at doctree.org

Run locally, self-host, or use doctree.org

doctree is a single binary, lightweight, and designed to run on your local machine. It can be self-hosted, and used via doctree.org with any GitHub repository.

Experimental! Early stages!

Extremely early stages, we're working on adding more languages, polishing the experience, and adding usage examples. It's all very early and not yet ready for production use, please bear with us!

Please see the v1.0 roadmap for more, ideas welcome!

Join us on Discord

If you think what we're building is a good idea, we'd love to hear your thoughts! Discord invite

Language support

Adding support for more languages is easy. To request support for a language comment on this issue

language functions types methods consts/vars search usage examples code intel
Go ✅ ✅ ❌ ❌ ✅ ❌ ❌
Python ✅ ❌ ❌ ❌ ✅ ❌ ❌
Zig ✅ ❌ partial ❌ ✅ ❌ ❌
Markdown n/a ❌ n/a n/a ✅ n/a n/a

Installation

macOS (Apple Silicon) 
curl -L https://github.com/sourcegraph/doctree/releases/latest/download/doctree-aarch64-macos -o /usr/local/bin/doctree
chmod +x /usr/local/bin/doctree
macOS (Intel) 
curl -L https://github.com/sourcegraph/doctree/releases/latest/download/doctree-x86_64-macos -o /usr/local/bin/doctree
chmod +x /usr/local/bin/doctree
Linux (x86_64) 
curl -L https://github.com/sourcegraph/doctree/releases/latest/download/doctree-x86_64-linux -o /usr/local/bin/doctree
chmod +x /usr/local/bin/doctree
Windows (x86_64) In an administrator PowerShell, run: 
New-Item -ItemType Directory 'C:\Program Files\Sourcegraph'

Invoke-WebRequest https://github.com/sourcegraph/doctree/releases/latest/download/doctree-x86_64-windows.exe -OutFile 'C:\Program Files\Sourcegraph\doctree.exe'

[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', [EnvironmentVariableTarget]::Machine) + ';C:\Program Files\Sourcegraph', [EnvironmentVariableTarget]::Machine)
$env:Path += ';C:\Program Files\Sourcegraph'

Or download the exe file and install it wherever you like.

Via Docker 
docker run -it --publish 3333:3333 --rm --name doctree --volume ~/.doctree:/home/nonroot/.doctree sourcegraph/doctree:latest

In a folder with Go code you'd like to see docs for, index it (for a large project like golang/go expect it to take ~52s for now. It's not multi-threaded.):

docker run -it --volume $(pwd):/index --volume ~/.doctree:/home/nonroot/.doctree --entrypoint=sh sourcegraph/doctree:latest -c "cd /index && doctree index ."
DigitalOcean user data 
#!/bin/bash

apt update -y && apt upgrade -y && apt install -y docker.io
apt install -y git

mkdir -p $HOME/.doctree && chown 10000:10001 -R $HOME/.doctree

# Index golang/go repository
git clone https://github.com/golang/go
chown 10000:10001 -R go
cd go
docker run -i --volume $(pwd):/index --volume $HOME/.doctree:/home/nonroot/.doctree --entrypoint=sh sourcegraph/doctree:latest -c "cd /index && doctree index ."

# Run server
docker rm -f doctree || true
docker run -d --rm --name doctree -p 80:3333 --volume $HOME/.doctree:/home/nonroot/.doctree sourcegraph/doctree:latest

Usage

Run the server:

doctree serve

Index a Go project (takes ~52s for a large project like golang/go itself, will be improved soon):

doctree index .

Navigate to http://localhost:3333

Contributing

We'd love any contributions!

To get started see docs/development.md and the language support tracking issue.

Changelog

v0.2 (not yet released)

  • Page downloads are now even slimmer (a few KiB for a a large Go package page.)
  • Fixed an issue where root Go project pages (e.g. github.com/gorilla/mux which contains only one Go package) would not render.

v0.1

  • Go, Python, Zig, and Markdown basic support
  • Basic search navigation experience based on experimental Sinter search filters
  • Searching globally across all projects, and within specific projects is now possible.
  • Searching within a specific language is now supported (add "go", "python", "md" / "markdown" to front of your query string.)
  • Markdown files now have headers and sub-headers indexed for search (e.g. # About doctree > Installation shows up in search)
  • Basic Markdown frontmatter support.
  • Initial doctree schema format
  • Experimental (not yet ready for use) auto-indexing, doctree add . to monitor a project for file changes and re-index automatically.
  • Docker images, single-binary downloads for every OS cross-compiled via Zig compiler.
  • Initial v1.0 roadmap, language support tracking issue

Special thanks: @KShivendu (Python support), @slimsag (Zig support)