Software tool to manage your notes, scripts, code examples, configs,... to publish them as gists or snippets
OTHER License
Code example manager (CEM) is a software managing your notes, scripts and code examples. It provides publish mechanisms to github.com (as gists) or gitlab.com (as snippets). It also automates execution for testable examples, this is a quite useful to manage a high number of examples.
All my notes, scripts and code examples (my programming knowledge base) are now managed using this tool, you can take a look to my public gists overview on github to illustrate the publishing work achieved by CEM.
Current Code example manager (CEM) implementation is just a command line tool which compare locally available examples with already published ones in order to find what it should do (add, update, do nothing).
Code examples are very important, each example is most of the time designed to focus on a particular feature/characteristic of a programming language, a library or a framework. They help us to quickly test, experiment and remember how bigger project or at least some parts of them are working.
See the rules for good code examples for more information.
Managing hundreds of published code example files as gists (github) and/or snippets (gitlab) is really not easy and time-consuming, in particular if you want to keep them up to date. This is the main issue addressed by this software.
As you can see through the previous charts, once you have industrialized your notes and code examples, analytics on your examples become quite easy, and a lot of advanced features become possible... So stay connected to this project ;)
No particular prerequisites, just a Java >=8 JVM available, and it will run on your Linux, Windows or MacOSX
Instructions example with github.com publishing configuration :
export CEM_SEARCH_ROOTS="/home/myuser/myexamples"
export CEM_GITHUB_TOKEN="xxxxx"
/home/myuser/myexamples
such as hello.md
<!--
// summary : my markdown cheat sheet
// keywords : markdown, hello, example
// publish : gist
// authors : someone, someonelse
// id : d27245fc-22fb-4c9e-9809-feb0826400e7
-->
# Hello world !
this is just an example
cs
is the coursier CLI command):
cs launch fr.janalyse:code-examples-manager_3:2.4.0
In order to be published your code examples must come with a description header inserted using single line comments. You must provide a unique identifier (UUID) to each of your example, as well as a summary and publish keywords which define remote destinations.
Example for languages using //
for line comments :
// summary : Simplest scalatest test framework usage.
// keywords : scala, scalatest, pi, @testable
// publish : gist
// authors : David Crosson
// license : Apache
// id : d24d8cb3-45c0-4d88-b033-7fae2325607b
// created-on : 2020-05-31T19:54:52Z
// run-with : scala-cli $file
// ---------------------
//> using scala "3.1.1"
//> using lib "org.scalatest::scalatest:3.2.10"
// ---------------------
import org.scalatest._, matchers.should.Matchers._
math.Pi shouldBe 3.14d +- 0.01d
Supported keys in description header are the following :
summary
: example summary in one line.keywords
: keywords describing your code features (comma separated). Some reserved keywords :
@testable
: allow automatic execution@fail
: the example is expected to fail when executed@exclusive
: all testable examples with this flag will be run sequentially (for scripts which open server sockets for example)publish
: publish destination keywords (comma separated)
gist
: for github.comsnippet
: for gitlab.comauthors
: code example authors list (comma separated).license
: the example license.id
: UUID for this code example. Generated using such commands :
attachments
: List of secondary files (comma separated) which must be published with the current one
created-on
: The ISO8601 date when this example has been created. Generated using such commands :
run-with
: command used to execute this example
@testable
keywords are eligible for automated execution$file
(or $scriptFile
) for example filename substitutiontest-with
: Command to test the example
@testable
is set as keywordtest-with : curl http://127.0.0.1:8080/docs
Code examples manager operations :
publish
keyword) select target destinations
activation-keyword
parameter in configuration)The configuration relies on configuration files, a default one named reference.conf
is provided.
This default configuration file defines default values and default behaviors and
allow a simple configuration way based on environment variables which override default values.
env or property name | description | default value |
---|---|---|
CEM_CONFIG_FILE | Your custom advanced configuration file (optional) | undefined |
CEM_SUMMARY_TITLE | The generated summary title for all published examples | Examples knowledge base |
CEM_SEARCH_ROOTS | Examples search roots (comma separated) | "" |
CEM_SEARCH_PATTERN | Examples files regular expression pattern | ".*" |
CEM_SEARCH_IGNORE_MASK | Ignore file regular expression | "(/[.]bsp) |
CEM_CHAR_ENCODING | Chararacter encoding for your examples or notes | "UTF-8" |
CEM_GITHUB_ENABLED | To enable or disable standard GITHUB support | true |
CEM_GITHUB_ACTIVATION_KEY | Example publish keyword for github | "gist" |
CEM_GITHUB_TOKEN | Github authentication token for gists API access | more information below |
CEM_GITHUB_API | Github API http end point | "https://api.github.com" |
CEM_GITLAB_ENABLED | To enable or disable standard GITLAB support | true |
CEM_GITLAB_ACTIVATION_KEY | Example publish keyword for the gitlab | "snippet" |
CEM_GITLAB_TOKEN | gitlab authentication token for snippets API access | more information below |
CEM_GITLAB_API | Gitlab API http end point | "https://gitlab.com/api/v4" |
CEM_GITLAB_VISIBILITY | Gitlab published examples chosen visibility | "public" |
Configuration examples :
export CEM_SEARCH_ROOTS="/tmp/someplace,/tmp/someotherplace"
export CEM_SEARCH_PATTERN="[.](sc)|(sh)|(md)|(jsh)$"
export CEM_GITHUB_TOKEN="fada-fada-fada-fada"
Take a look to the configuration file for more information about advanced configuration.
Once CEM installed you can modify the provided conf/application.conf
file (whose content is by default
the same as the default reference.conf file), remember that any unset parameter in application.conf
will default to the value defined in reference.conf
.
Note : It is also possible to provide a custom configuration file through the config.file
java property or the
CEM_CONFIG_FILE
environment variable.
Get an access token from gitlab :
api
and read_user
CEM_GITLAB_TOKEN
environment variable or token
parameter in your configuration fileGet an access token from gitlab.com :
gist
and read:user
CEM_GITHUB_TOKEN
environment variable or token
parameter in your configuration file