hscloud/devtools/hackdoc/README.md

Hackdoc
=======

Hackdoc is a tool to automatically serve documentation based on a checkout of the [hscloud](/) source.

Usage
-----

Any Markdown submitted to hscloud is visible via hackdoc. Simply go to https://hackdoc.hackerspace.pl/path/to/markdown.md to see it rendered.

You can pass a `?ref=foo` URL parameter to a hackdoc URL to get it to render a particular vesrion of the hscloud monorepo. For example:

- https://hackdoc.hackerspace.pl/?ref=master for the `master` branch
- https://hackdoc.hackerspace.pl/?ref=change/249 for the the source code at change '249'

Special Markdown
----------------

We should be accepting a Somewhat Standard Subset Of Markdown. For reference, we're using the [blackfriday](https://godoc.org/github.com/russross/blackfriday/v2) library with [CommonExtensions](https://godoc.org/github.com/russross/blackfriday/v2#CommonExtensions) enabled.

In addition, we also support Table of Contents autorendering, just place the following anywhere in your document to render a TOC:

    [TOC]


Local Rendering
---------------

To run hackdoc locally on a filesystem checkout (ie. when working on docs, templates, or hackdoc itself), run:

     bazel run //devtools/hackdoc  -- -hspki_disable -docroot /path/to/hscloud

The output log should tell you where hackdoc just started listening at. Currently this is `127.0.0.1:8080` by default. You can change this by passing a `-pub_listen` flag, eg. `-pub_listen 127.0.0.1:4242`.
devtools/hackdoc: init This is hackdoc, a documentation rendering tool for monorepos. This is the first code iteration, that can only serve from a local git checkout. The code is incomplete, and is WIP. Change-Id: I68ef7a991191c1bb1b0fdd2a8d8353aba642e28f 2020-04-08 18:03:12 +00:00			`Hackdoc`
			`=======`

			`Hackdoc is a tool to automatically serve documentation based on a checkout of the [hscloud](/) source.`

			`Usage`
			`-----`

			`Any Markdown submitted to hscloud is visible via hackdoc. Simply go to https://hackdoc.hackerspace.pl/path/to/markdown.md to see it rendered.`

devtools/{depotview,hackdoc}: tie both together Change-Id: I0a1ca3b4fa0e0a074eccbe0f8748839b926db9c1 2020-04-10 15:39:43 +00:00			You can pass a `?ref=foo` URL parameter to a hackdoc URL to get it to render a particular vesrion of the hscloud monorepo. For example:

			- https://hackdoc.hackerspace.pl/?ref=master for the `master` branch
			`- https://hackdoc.hackerspace.pl/?ref=change/249 for the the source code at change '249'`

hackdoc: render TOC inline Change-Id: Ib91e4d3b73354e7e19095ea62eed70a23ef96512 2020-09-23 18:13:05 +00:00			`Special Markdown`
			`----------------`

go: re-do the entire thing This is a mega-change, but attempting to split this up further is probably not worth the effort. Summary: 1. Bump up bazel, rules_go, and others. 2. Switch to new go target naming (bye bye go_default_library) 3. Move go deps to go.mod/go.sum, use make gazelle generate from that 4. Bump up Python deps a bit And also whatever was required to actually get things to work - loads of small useless changes. Tested to work on NixOS and Ubuntu 20.04: $ bazel build //... $ bazel test //... Change-Id: I8364bdaa1406b9ae4d0385a6b607f3e7989f98a9 Reviewed-on: https://gerrit.hackerspace.pl/c/hscloud/+/1583 Reviewed-by: q3k <q3k@hackerspace.pl> 2023-07-28 17:14:50 +00:00			`We should be accepting a Somewhat Standard Subset Of Markdown. For reference, we're using the [blackfriday](https://godoc.org/github.com/russross/blackfriday/v2) library with [CommonExtensions](https://godoc.org/github.com/russross/blackfriday/v2#CommonExtensions) enabled.`
hackdoc: render TOC inline Change-Id: Ib91e4d3b73354e7e19095ea62eed70a23ef96512 2020-09-23 18:13:05 +00:00
			`In addition, we also support Table of Contents autorendering, just place the following anywhere in your document to render a TOC:`

			`[TOC]`


devtools/hackdoc: init This is hackdoc, a documentation rendering tool for monorepos. This is the first code iteration, that can only serve from a local git checkout. The code is incomplete, and is WIP. Change-Id: I68ef7a991191c1bb1b0fdd2a8d8353aba642e28f 2020-04-08 18:03:12 +00:00			`Local Rendering`
			`---------------`

			`To run hackdoc locally on a filesystem checkout (ie. when working on docs, templates, or hackdoc itself), run:`

*: more hackdoc updates Change-Id: Ib9830c66fe36c423d38f447905c470b67cde5399 2020-04-10 19:20:53 +00:00			`bazel run //devtools/hackdoc -- -hspki_disable -docroot /path/to/hscloud`
devtools/hackdoc: init This is hackdoc, a documentation rendering tool for monorepos. This is the first code iteration, that can only serve from a local git checkout. The code is incomplete, and is WIP. Change-Id: I68ef7a991191c1bb1b0fdd2a8d8353aba642e28f 2020-04-08 18:03:12 +00:00
hackdoc: fix pub_listen flag in readme Change-Id: I5d41fa12f29ec5cff9251bb0ad77fc5fdafef786 2020-09-23 18:12:41 +00:00			The output log should tell you where hackdoc just started listening at. Currently this is `127.0.0.1:8080` by default. You can change this by passing a `-pub_listen` flag, eg. `-pub_listen 127.0.0.1:4242`.