From cdc29e26153fc8c155f13de3568bf1db54ceeeb0 Mon Sep 17 00:00:00 2001 From: Cadence Ember Date: Sun, 4 Sep 2022 16:07:28 +1200 Subject: [PATCH] Docs --- custom-style.css | 59 +++++++++++++++++++ docs.scrbl | 132 +++++++++++++++++++++++++++++++++++++++++++ scribble-prefix.html | 1 + 3 files changed, 192 insertions(+) create mode 100644 custom-style.css create mode 100644 docs.scrbl create mode 100644 scribble-prefix.html diff --git a/custom-style.css b/custom-style.css new file mode 100644 index 0000000..a6cba1d --- /dev/null +++ b/custom-style.css @@ -0,0 +1,59 @@ +html { + font-size: 18px; +} + +body { + display: grid; + justify-content: center; + grid-template-columns: auto minmax(auto, 750px); + gap: 20px; + padding-bottom: 10vh; +} + +.tocset, .maincolumn { + float: none; + margin: 0; +} + +.tocviewlist table { + font-size: 1rem; +} +.tocviewsublist table, +.tocviewsublistonly table, +.tocviewsublisttop table, +.tocviewsublistbottom table { + font-size: 0.85rem; +} + +.toclink, .toptoclink, .tocviewlink, .tocviewselflink { + text-decoration: none; +} +.toclink:hover, .toptoclink:hover, .tocviewlink:hover, .tocviewselflink:hover { + text-decoration: underline; +} + +.maincolumn { + width: auto; +} + +h3 { + font-size: 1.6em; +} +h4 { + font-size: 1.3em; +} + +.boxed, .SVerbatim, .stt { + background-color: rgb(232, 232, 255); + font-size: 0.90em; +} + +@media (max-width: 600px) { + body { + grid-template-columns: 1fr; + } + + .tocset { + width: auto; + } +} diff --git a/docs.scrbl b/docs.scrbl new file mode 100644 index 0000000..a8efc5e --- /dev/null +++ b/docs.scrbl @@ -0,0 +1,132 @@ +#lang scribble/base + +@(require scribble/manual) +@(define (code . pre-content) (elem (apply literal pre-content) #:style 'tt)) + +@title{BreezeWiki Documentation} + +@url{https://breezewiki.com} + +@local-table-of-contents[] + +@; ----------------------------------------------------------------------------- + +@section{Links} + +@itemlist[ +@item{Source code: @url{https://gitdab.com/cadence/breezewiki}} +@item{How to bug report or feature request: @Secref["Reporting Bugs"]} +@item{Planned features: } +@item{Community: @url{https://matrix.to/#/#breezewiki:cadence.moe}} +] + +@; ----------------------------------------------------------------------------- + +@section[#:tag "Reporting Bugs"]{Reporting Bugs} + +Bug reports are important, and so are feature requests! Thank you for your interest. Here's how to send in yours. + +There is the @italic{mailing list} which is the first line for people like you to report to. Once a bug is confirmed, I will copy it onto the @italic{todo tracker} as a task item. + +Please spend one minute checking the todo tracker so you don't submit a duplicate of somebody else's report. + +For real-time chat with the community, check out @url{https://matrix.to/#/#breezewiki:cadence.moe}. + +@subsection{Actually sending a report} + +To actually send in your report, compose an email to @hyperlink["mailto:~cadence/breezewiki-discuss@lists.sr.ht" "~cadence/breezewiki-discuss@lists.sr.ht"] with a useful subject line and a description. + +Please make sure to include the following information: + +@itemlist[ +@item{Which URL can I visit to see it for myself?} +@item{Which part of the page are you talking about?} +@item{Does it happen every time?} +] + +Thanks! + +@; ----------------------------------------------------------------------------- + +@section{Running} + +@subsection{Running a compiled executable} + +This method is recommended for people who do not want to edit the source code. + +The distribution includes the Racket runtime, libraries, and everything else needed to run BreezeWiki. + +@itemlist[#:style 'ordered +@item{Download the distribution: @url{https://cadence.moe/friends/breezewiki-dist.tar.gz}} +@item{Unpack the archive.} +@item{Execute the binary @code{breezewiki-dist/bin/dist}.} +] + +@subsection{Running the source code} + +This method is recommended for people who want to edit the source code, or for people who can't use the compiled distribution. + +@itemlist[#:style 'ordered +@item{Install Racket. Please install the latest version. 8.4 or later is required.} +@item{Clone the repository from @url{https://gitdab.com/cadence/breezewiki}.} +@item{Run @code{raco pkg install --auto --skip-installed} in the repository to install dependencies.} +] + +Now you can start BreezeWiki using one of the following methods. + +@itemlist[ +@item{Run @code{racket dist.rkt} to start BreezeWiki.} +@item{Evaluate @code{breezewiki.rkt} in DrRacket or in the Racket REPL to start BreezeWiki with module hot-reloading. Helpful for development!} +] + +To be able to start up BreezeWiki faster, use @code{raco make dist.rkt} to byte-compile individual files. + +@; ----------------------------------------------------------------------------- + +@section{Configuration} + +@subsection{File} + +Configuration options are added to the @code{config.ini} file. It is a regular INI file. + +If you do not specify a specific option, the internal default will be used. If the file is missing or empty, all defaults will be used. + +If you're using a compiled distribution of BreezeWiki, the main @code{config.ini} file will actually be a symlink to the real location of the file. Make sure not to erase the symlink, or your settings will be ignored! + +@subsection{Example} + +Here is an example configuration file. It shows all the available settings and all their defaults. +@verbatim{ +canonical_origin = +debug = false +port = 10416 +} + +@subsection{Format} + +@itemlist[ +@item{A line with an equals sign @code{=} defines one setting.} +@item{The text before the equals sign is the @italic{key}.} +@item{The text after the equals sign is the @italic{value}. It may be empty.} +@item{Quote marks are optional - they are never necessary.} +@item{Spacing around the equals sign is optional.} +@item{@italic{False} values are represented by either empty space, or the text @code{false}. Anything else is @italic{True}.} +] + +@subsection{Detailed Options} + +@defthing[debug boolean #:value false]{ +Enables debugging mode, for debugging BreezeWiki during development. + +Enables more runtime checks and more verbose output. Turns off some browser caching. +} + +@defthing[port value #:value "10416"]{ +Which port to run the server on. +} + +@defthing[canonical_origin value #:value ""]{ +The URL that the homepage of the instance is intended to be accessed at. + +For example, @code{https://breezewiki.com} +} diff --git a/scribble-prefix.html b/scribble-prefix.html new file mode 100644 index 0000000..0e76edd --- /dev/null +++ b/scribble-prefix.html @@ -0,0 +1 @@ +