-
Notifications
You must be signed in to change notification settings - Fork 24
Documentation Systems
There are several "phases" to this process: content creation, content editing, and content publishing. For each phase there are many possible workflows.
- A static website means that you prepare a bunch of html files and put them in a folder that is web-accessible.
- A dynamic website means that you have a server running some code that builds a web-page a request is made.
- A "local" website could be static or dynamic but generally means that you are not using the internet - you are serving the web-pages locally, on your machine, to yourself (or perhaps other people on your LAN - local area network)
- A wiki is a specific type of website. Definition from wikipedia:
A wiki is a hypertext publication collaboratively edited and managed by its own audience directly using a web browser. A typical wiki contains multiple pages for the subjects or scope of the project and could be either open to the public or limited to use within an organization for maintaining its internal knowledge base.
Many other types of possible documentation documents: printed book, pdfs ppts, drawings, word docs, podcast, etc
A markup language (for our purposes here) is for annotating text with extra information that can be used to control the formatting.
There are many flavors of markup languages (html, xml, markdown, reStructuredText, Rdoc, Textile, etc, etc). The annotated text document is then set thru a text processor that translates the markup into special formatting (bold, indented, colors, size, font, etc, etc), and builds the resulting document, whether that is an html document (web page) or a pdf.
Github makes extensive use of markup languages on their website allowing text to be written and version controlled in the markup language and displayed with nice formatting on their website.
Each markup language has slightly different features and strengthas. This document is written using Markdown. One of the reasons I chose markdown is that the annotated plain text is relatively easy to read. This is nice for writing the document, and also means the document is pretty readable even when you don't have access to the translation software.
Most text editors and IDEs have support for sytax highlighting of most common markup languages.
In order to allow for automatic generation of table of contents and automated conversion between different document formats, documents must be structured. This means that the standard headings should be used to define the document outline (instead of simply making section titles bold for example).
Both of these tools handle the content creation/editing part as well as the publishing.
Uses a static site generator software named https://jekyllrb.com to generate html files and
host them on github's servers. The jekyll software runs on Github servers and generates the new html files when certain things occur, i.e. pushing code to the gh_pages branch.
From the website:
Jekyll is a static site generator. It takes text written in your favorite markup language and uses layouts to create a static website. You can tweak the site’s look and feel, URLs, the data displayed on the page, and more.
- could be independant repo
- or could be gh-pages branch in our repo
- could be docs/ folder in our repo
Content creation is done locally on your computer, using a text editor, and writing in a markup language, and publishing happens when you push to Github, which triggers Jekyll, on Github's severs to regenerate the site.
- not sure how to test locally? I guess just install jekyll? might be hard to perfectly duplicate github's results
The look and feel of a Jekyll site is entirely customizeable via themes. Images can be included in a folder and linked to in the markup text, or could be provided via Google Drawing embed tags.
Uses a static site generator software named (gollum)[https://github.com/gollum/gollum] to generate html files and host them on github's servers. The gollum software runs on github servers and generates new html files when certain things occur, such as pushing to the master branch of the wiki repo, or using the online editor (which makes a commit when you save).
Creation is done either locally on your computer or in the online editors on Github site. Publshing is happens when pushing or comitting to the Github repo (the wiki specific repo, i.e. https://github.com/ua-snap/dvm-dos-tem.wiki.git). Github takes care of the web hosting for us.
From the website:
Gollum is a simple wiki system built on top of Git. A Gollum Wiki is simply a git repository of a specific nature.
- editable online
- editable by cloning wiki and editing locally, then pushing back to github
Images:
- make google drawing, put embed code in wiki text
- editability depends on access to the google drawing
- only works with google drawings
- clone wiki to local, add image to images folder, push back
- not easy to edit unless you have the original file (.ppt, .ai, .ps, etc)
- requires git
Doxygen is used to build a static website from comments that are in our C++ code. Python's sphinx or doctest librarys are similar. There are many other similar tools for different languages. Neither doctest or doxygen do anything about publishing the resulting product.
Use case to-date has been that each interested person clones the repo, installs doxygen, runs doxygen over the code, and looks at the resulting web pages locally (i.e. file:///Users/joe-schmo/dvm-dos-tem/docs/index.html).