LFE Documentation Site
Documentation source for Lisp Flavoured Erlang
When I first came here, this was all yak hair. Everyone said I was daft to build a yurt on the Endless High Plain of Yak, but I built in all the same, just to show them. It sank into the Plains of Yak. So I built a second one. That sank into the Plains of Yak. So I built a third. That burned down, fell over, then sank into the Plains of Yak. But the fourth one stayed up. And that's what you're going to get, the strongest yak hair yurt on the Endless High Plain of Yak.
Build for failure? No! Build to burn down, fall over, and sink into the Plains of Yak!
This is the source code that generates the site for the LFE documentation. The last stable release is always available here:
And the current development work on the docs is published here:
Note that the latest dev version provides a drop-down menu in the top-nav for accessing previous releases of the LFE Documentation.
The aim of this project is twofold:
- Maintain the content for the LFE documentation site
- Maintain a tool (written in LFE) for generating the LFE docs site
The next release of the docs site and tooling is v3.1. All tickets for the release are ulimately linked here:
If you want to regenerate the CSS, you'll need
make sassto install; requires Ruby +
gemto be installed)
There are two supported ways of building the LFE docs site and CSS:
maketargets (which call erlang under the hood)
docsfunctions from the LFE REPL
To (re)generate the static files:
$ make docs-dev
That will build both the HTML files as well as the CSS.
To only build the HTML:
$ make docs-dev-only
To only build the CSS:
$ make css-dev
make target is provided which compiles everything fresh,
starts up a local dev HTTP server, and watches for changes in CSS, HTML
templates, and LFE code:
$ make serve-dev-watch
The CSS watcher is a backgrounded
sass process, and not native LFE, so you
will need to kill it when you are done:
$ make css-unwatch
To (re)generate the static files, start up an LFE REPL:
$ make repl
Erlang/OTP 18 [erts-7.3] [source] [64-bit] [smp:4:4] [async-threads:10] ... ..-~.~_~---.. ( \\ ) | A Lisp-2+ on the Erlang VM |`-.._/_\\_.-': | Type (help) for usage info. | g |_ \ | | n | | | Docs: http://docs.lfe.io/ | a / / | Source: http://github.com/rvirding/lfe \ l |_/ | \ r / | LFE v1.3-dev (abort with ^G) `-E___.-' lfe> (docs:start) ok
To generate the docs to dev:
lfe> (docs-cli:gen-dev) Created docs/dev/index.html. ... ok
Or to generate the static files to prod (the
current directory; this is
only done when promoting dev to stable):
lfe> (docs-cli:gen) Created docs/current/index.html. ... ok
To run a local copy of the development server and view your work at http://localhost:8080, run the following:
lfe> (docs-cli:start-httpd) ok
or for dev server
lfe> (docs-cli:gen-dev-httpd) ok
The CSS files are managed with sass. After changing
values in the
priv/sass/lfe*.scss files or in the
priv/sass/lfe-sass/ subdirectories, you'll need to rebuild:
$ make css
This part of the documentation (and code, for that matter) is under very active development and is changing regularly, but as it stands right now, the following steps outline how to add new content to the LFE Documentation site.
- Fork this repository.
git cloneyour fork to your local machine and
cdto the working directory of your clone. If you will be making CSS changes, you'll need the
bootstrap-sasssubmodule. In that case, you'll want to use
git clone --recursiveand
git clone --recursive --depth 1.
- If you plan on making content additions, you'll want to select the
template you want to base your page on (e.g.,
- Create a new template that extends your selected template, overriding the block with content in your new template (see the other templates for examples of this).
- Update the
docs-pages:get-pagefunction with a clause that will match your page
- If you need a custom data function that sets variables that need to be
substituted in your template, be sure to call it here in the
get-pagefunction (after you add it to
- Also, in the
get-pagefunction is where you will call your template's
- Make sure your
get-pagecode extracts the results of the
renderfunction (e.g., using the provided
get-contentfunction in the same module).
- If you need a custom data function that sets variables that need to be substituted in your template, be sure to call it here in the
- Make sure that your clone of
lfe/docshas the submodule populated (check the
- Make updates to the file
- If you need to create some new variables, you'll want to edit
- Commit your changes to the sass files.
- Regenerate the dev CSS with
Generation & Testing
- Start up the LFE REPL (e.g.,
- Generate the static content with
- Serve the newly generated content with
- Or do all of those with one target:
- Visit http://localhost:8080/dev/index.html and any other pages you need to test.
- Once you are sure it's good, commit the changes.
Caution: Do not run
(docs-cli:gen), as that will generate an updated stable
version of the docs (the contents of the
current) directory. That is only
done prior to a new release of LFE and/or the documentation site. Any PRs that
current will not be approved until those changes are removed (modulo
typo fixes and the like).
If you have called
(docs-cli:gen) by accident, simply do a
git checkout of the
current dir to undo the docs regen.
- Push to your fork on Github.
- Open a PR.
Copyright © 2013-2017 LFE Community Distributed under the Apache License, Version 2.0.