commit | f511101ab62287bc10a7738f1cab19ac09aff5d0 | [log] [tgz] |
---|---|---|
author | Michael Beckerle <mbeckerle@tresys.com> | Fri Oct 25 20:48:56 2019 -0400 |
committer | Mike Beckerle <mbeckerle@tresys.com> | Thu Dec 12 10:07:52 2019 -0500 |
tree | 22653cf72253ece14d9792ad1f7f0015283d0e7b | |
parent | 3b2735c188487232460cf0b23cffdb740c3a8dc7 [diff] |
Add tutorials to site, add AsciiDoc and Diagrams capability. Added tutorials and their stylesheet to the site so we can start to present this to people and grow them. Added Asciidoc and especially asciidoctor-diagrams capability to site so jekyll tool will run these tools to create more advanced content with diagrams, etc. I added this because I got tired of the markdown wars between github, confluence, etc. AsciiDoc has some significant advantages over those, including embedded diagram support. I am looking at creating a bunch of technical doc now and ongoing, and I just can't see using Confluence Wiki for it, and other markdown systems don't have the diagrams capability worked out that AsciiDoc has. There's no content in this yet using AsciiDoc except an aboutAsciiDoc page that serves as a example/demo of the various digram capabilities. (Illustrates why I really like AsciiDoc!) Instructions updated to show how to install the new tooling (extensions for jekyll). The tutorials and AsciiDoc page are mostly sharing stylesheets and style with the rest of the site. I still don't have the asciidoc stylesheets working quite right. When you use a TIP, CAUTION, NOTE, etc., in AsciiDoc files (".adoc") the graphical icon doesn't show up. The source code examples are too light, etc. In addition, in the dev daffodil repo, scripts/release-candidate.sh copies tutorial ".tdml.xml" files (actually all files in that dir) from the daffodil tree to this site tree because the tutorial files are actual tests and we don't want them to ever become stale/non-working. (That's the whole point of them being in TDML) Add .jekyll-cache to .gitignore to avoid accidentally committing that. DAFFODIL-2004
The Apache Daffodil (incubating) web site is based off of the Apache Website Template.
The website is generated using Jekyll and some plug-ins for it.
Some Linux distributions provide Jekyll via their package managers, for example, for Fedora 25
$ dnf install rubygem-jekyll
Alternatively, Jekyll can be installed using gem:
$ gem install jekyll
Some content is developed using the AsciiDoc Markdown variant, which supports embedded diagrams created from diagram-specifying text formats.
(You probably want to install these as super-user using sudo.)
$ gem install jekyll-asciidoc $ gem install asciidoctor-diagram $ apt install python-pip $ pip install blockdiag $ pip install seqdiag $ pip install actdiag $ pip install nwdiag
NOTE: nwdiag
actually supports more than one diagram type. It supports nwdiag, packetdiag, rackdiag, etc.
Before opening a pull request, you can preview your contributions by running from within the directory:
$ jekyll serve --watch --source site
Open http://localhost:4000 to view the site served by Jekyll.
Once satisfied, create a branch and open a pull request using the Daffodil project Code Conttributor Workflow but using the website repo instead of the code repo.
Daffodil uses gitpubsub for publishing to the website. The static content served via apache must be served in the content
directory on the asf-site
orphan branch. Use the publish.sh
script script exists to create this content:
$ ./publish.sh $ git push asf asf-site