Janetdocs

Community documentation for Janet, forked from janetdocs made with Joy.

Get Started

0. Clone this repo and install Janet. May need curl: apt-get install libcurl4-openssl-dev.

1. Make and fill out .env like .env.sample

2. Make github oauth app to enable signing in. The callback url looks like: https://example.com/github-auth You can use an IP address or localhost for the of url.

3. Enter the this project's directory then:

• Install deps: jpm deps
• Migrate DB: joy migrate
• Import "blessed packages" (the [final section](# import-blessed-packages) has a dangerous script)
• Seed DB: janet seed.janet
• Fill DB: janet importer.janet

4. That's it, just run: janet main.janet and visit localhost:9001! Poke around the code and learn what's going on!

Issues

• many blessed packages don't build, import, have name collisions or require certain OS...
  • I can save some, maybe
• users can't
  • add examples without github account
  • add new bindings
  • add "see-also"
  • add / choose packages
• have not updated dockerization since Swlkr
• users search all packages, would be interesting to search without package prefix, to surface available bindings

Ideas

• replace uri/escape and uri/unescape with own escaper, or upstream some changes
  • but confirm it incorrectly handles turning /% into /%25 and that wasn't my error
  • modify relevant sections marked via # note jdocs-escape https://github.com/janet-lang/janet-lang.org/blob/master/content/api/gen-docs.janet
• display binding docs above examples in the playground
• go to binding source button
  • https://github.com/pyrmont/documentarian can make cool stuff like: github.com/pyrmont/testament@ea1dd414b8/api.md
• iterate through the DB (example bodies) parsing with janet-peg/rewrite/par to find which err (and could thus use some # to comment things out)

---

Notes

• run ssl-fetcher.janet with a cronjob weekly for https
• ao-dark.css and ao-light.css determine example colors (my modified atom-one-dark and light had hljs which I removed, maybe that standard is better though and I'll return to them circa commit 4cf36bba62)
• the playground is a separate project. I upstream what improvements I can and made mode-janet.js. It uses ace.js and styling comes from custom.js assigned in jdocs_playground.js.
• I removed depricated functions' examples: thread/receive, thread/send, tarray/new

To Update/Build the Playground

0. Install emscripten and download the playground repo.

1. cd to the playground repo and run:

• jpm deps
• ./playground update-janet latest
• ./playground build
• ./playground install

2. Move janet.js and .janet.wasm from its public/js to this public/playground

Import Blessed Packages

This is reduced from the official pkgs list. To import their bindings, we must install them with jpm, which is raher dangerous as they may contain arbitrary c code, so if a single maintainer is pwned... For this reason, I did not automate seeding, but the list is a moving target, so maybe I should.

Install libprimesieve-dev libpq-dev libhiredis-dev for some of these, then:

sudo jpm install \
https://github.com/janet-lang/sqlite3.git \
https://github.com/cosmictoast/jurl.git \
https://github.com/Techcable/janet-msgpack.git \
https://git.sr.ht/~pepe/eleanor \
https://github.com/andrewchambers/janet-rlrepl.git \
https://git.sr.ht/~pepe/marble \
https://git.sr.ht/~pepe/manisha \
https://git.sr.ht/~nullevoid/args \
https://git.sr.ht/~nullevoid/gapbuffer \
https://github.com/levitanong/jdn-loader.git \
https://github.com/andrewchambers/janet-pq.git \
https://git.sr.ht/~pepe/shawn \
https://github.com/MikeBeller/janet-set.git \
https://github.com/andrewchambers/janet-process.git \
https://github.com/andrewchambers/janet-uri.git \
https://git.sr.ht/~subsetpark/fugue \
https://github.com/bakpakin/mendoza.git \
https://github.com/yumaikas/janet-stringx.git \
https://git.sr.ht/~pepe/trevor \
https://git.sr.ht/~pepe/trolley \
https://github.com/janet-lang/jpm.git \
https://git.sr.ht/~bakpakin/temple \
https://github.com/andrewchambers/janet-redis.git \
https://github.com/janet-lang/jhydro.git \
https://git.sr.ht/~pepe/bonzer \
https://git.sr.ht/~pepe/chidi \
https://codeberg.org/amano.kenji/j3blocks.git \
https://github.com/ianthehenry/judge.git \
https://github.com/joy-framework/tester.git \
https://github.com/andrewchambers/janet-base16.git \
https://github.com/andrewchambers/janet-flock.git \
https://github.com/wooosh/janet-openssl-hash \
https://github.com/pyrmont/testament.git \
https://github.com/janet-lang/circlet.git \
https://github.com/jeannekamikaze/janet-filesystem.git \
https://github.com/janet-lang/jaylib.git \
https://github.com/janet-lang/argparse.git \
https://github.com/Jakski/janet-base64.git \
https://git.sr.ht/~statianzo/janet-nanoid \
https://github.com/janet-lang/pkgs.git \
https://github.com/janet-lang/spork.git \
https://github.com/joy-framework/joy.git \
https://github.com/bakpakin/janet-miniz.git \
https://codeberg.org/amano.kenji/janet-utf8.git \
https://git.sr.ht/~pepe/michael \
https://codeberg.org/amano.kenji/janet-repl-tools.git \
https://git.sr.ht/~pepe/bearimy \
https://github.com/cosmictoast/janet-date.git \
https://git.sr.ht/~pepe/kamilah \
https://git.sr.ht/~pepe/hemple \
https://github.com/ianthehenry/cmd.git \
https://github.com/andrewchambers/janet-sh.git

# fine, but too many (undocumented) functions
# https://git.sr.ht/~p/jermbox \
# https://gitlab.com/jeannekamikaze/janet-glfw.git \

# these don't install: jlzf glyph shriek
# https://git.sr.ht/~nullevoid/jlzf \
# https://github.com/tionis/glyph.janet.git \
# https://git.sr.ht/~pepe/shriek \

# these won't import although build was fine:
# 'bigint 'freja 'x43bot 'html 'openbsd 'juv 
# https://github.com/andrewchambers/janet-big.git \
# https://github.com/sepisoad/jtbox.git \
# https://github.com/saikyun/freja.git \
# https://github.com/bakpakin/x43bot.git \
# https://github.com/swlkr/janet-html.git \
# https://git.sr.ht/~les/janet-openbsd \
# https://github.com/janet-lang/juv.git \

# msgpack has name colision with spork
# error: cannot register abstract type ta/buffer, a type with the same name exists
#   in native [src/core/corelib.c] on line 288
#   in native-loader [boot.janet] on line 3068, column 40
#   in require-1 [boot.janet] on line 3096, column 18
#   in import* [boot.janet] on line 3129, column 15
#   in thunk [/usr/local/lib/janet/spork/init.janet] (tail call) on line 45, column 1
#   in dofile [boot.janet] (tail call) on line 3060, column 7
#   in source-loader [boot.janet] on line 3072, column 15
#   in require-1 [boot.janet] on line 3096, column 18
#   in import* [boot.janet] on line 3129, column 15
#   in thunk [repl] (tail call) on line 33, column 11
#   
#   tarray colision with spork
#   error: cannot register abstract type ta/buffer, a type with the same name exists
  # in native [src/core/corelib.c] on line 288
  # in native-loader [boot.janet] on line 3068, column 40
  # in require-1 [boot.janet] on line 3096, column 18
  # in import* [boot.janet] on line 3129, column 15
  # in thunk [repl] (tail call) on line 19, column 11