- Curl
- Git
- GNU Find
- GNU Make
- Python 3
Makefile # Defines the make targets
python/ # Python library code; used by scripts
scripts/ # Scripts called by the make rules
input/ # The site content before rendering
output/ # Rendered result for local testing
content/ # Rendered result for publication to the site
Some notable files in input/:
input/_transom_template.html # The standard page template
input/_transom_config.py # Site variables, values for {{placeholders}}
input/site.js # Site javascript code
input/site.css # Site CSS
After that most everything is accomplished by running make targets. These are the important ones:
[qpid-site]$ make render # Renders input/* to output/
[qpid-site]$ make clean # Removes output/
[qpid-site]$ make publish # Renders input/* to content/ in preparation
# for a live site update
-
Use your editor to create or edit a file under
input/[qpid-site]$ emacs input/somepage.md -
Render the site
[qpid-site]$ make render -
To look at the result in your browser, navigate to
file:/<some-path>/qpid-site/output/somepage.html
The render operation takes files under input/ and reproduces them
under output/. The following transformations are applied in the
process.
.html.infiles are wrapped in the standard page template and copied..md(Markdown) files are converted to HTML, wrapped in the site template, and copied.- All other files are simply copied.
- All Markdown, HTML, Javascript, and CSS files undergo substitution
for
{{placeholders}}.
Markdown is a markup language inspired by plain text conventions. This page is written in markdown. See this syntax guide.
The particular markdown implementation the site code uses is python-markdown2.
I personally benefit from using emacs markdown mode. On
Fedora it is part of the emacs-goodies package.
input/_transom_config.py defines some variables usable for any input
page. To illustrate:
{{site_url}} -> http://qpid.apache.org
{{current_proton_release}} -> 0.17.0
{{current_dispatch_release}} -> 0.8.0
Under output/, {{site_url}} is set to a path in your development
environment, to allow for local testing. Under content/,
{{site_url}} is set to http://qpid.apache.org, for publication to
the live site.
You can see more definitions in input/_transom_config.py.
See http://qpid.apache.org/site.html#style-guide for site guidelines for formatting and style.
The site tools offer a way to check that all your hyperlinks are working.
# Usage: make check-links [INTERNAL=1] [EXTERNAL=0]
# Check internal links only
[qpid-site]$ make check-links
# Check external links as well
[qpid-site]$ make check-links EXTERNAL=1
Content for new releases is generated using scripts. Use one of the following commands.
# Usage: make gen-$module-release RELEASE=$VERSION [CHECKOUT_DIR=$DIR]
# For new Qpid C++ releases
[qpid-site]$ make gen-cpp-release RELEASE=$VERSION
# For new Qpid Broker-J releases
[qpid-site]$ make gen-broker-j-release RELEASE=$VERSION
# For new Qpid JMS releases
[qpid-site]$ make gen-jms-release RELEASE=$VERSION
# For new Qpid Proton releases
[qpid-site]$ make gen-proton-release RELEASE=$VERSION
# For new Qpid Proton-J releases
[qpid-site]$ make gen-proton-j-release RELEASE=$VERSION
# For new Qpid Dispatch releases
[qpid-site]$ make gen-dispatch-release RELEASE=$VERSION
# For new Qpid Interop Test Releases
[qpid-site]$ make gen-interop-test-release RELEASE=$VERSION
These will produce a new tree of release content under
input/releases/. The content includes API docs, examples, and
books. Once generated, you can make any edits you'd like and check it
in.
In addition to specifying RELEASE, you can override the particular
release identifier used for querying issues and exporting source using
ISSUES_RELEASE and SOURCE_RELEASE respectively. If not set,
ISSUES_RELEASE and SOURCE_RELEASE take the value of RELEASE.
By default, the scripts will fetch the source for you based on the
release script inputs. By setting the optional CHECKOUT_DIR
parameter to the location of a local Subversion checkout, the scripts
will instead use the provided content.
When you add release content, you should also update the following files.
input/_transom_config.py # Update the current release pointer
input/releases/index.md # Add current release, move the previous
The scripts depend on the availability of the following tools in your environment: asciidoc, asciidoctor, cmake, dot, doxygen, epydoc, fop, gcc, javadoc, make, pygments, PyYAML, rdoc, git, pandoc, pdflatex, xsltproc, and yard. The following yum command works to install all the required dependencies on Fedora or RHEL.
$ sudo yum install asciidoc asciidoctor cmake doxygen epydoc \
fop gcc graphviz java-devel libxslt make python-pygments \
python3-pyyaml rubygem-rdoc git pandoc-pdf python-sphinx maven \
rubygem-yard
Qpid uses gitpubsub to send new content to the Qpid website. Any file
committed under the content/ directory on the asf-site branch of
the https://gitbox.apache.org/repos/asf/qpid-site.git repo is
automatically propagated to the live site. make publish renders to
this same content/ directory.
To publish, run make publish and use git to commit and push the
changes. Any additions or other structural changes under the input/ and
content/ directories may require git adds or removes.
[qpid-site]$ make publish
scripts/render "" input content
git status input content
# On branch asf-site
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: content/discussion.html
# modified: input/discussion.md
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# content/new_file.html
# input/new_file.md
no changes added to commit (use "git add" and/or "git commit -a")
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NOTICE! One more step remains!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use git to commit and push the changes.
Keep in mind that you may need to git add new files.
Also keep in mind to git rm matching files from content/ that have been removed from input/.
- The Qpid site code internally uses Transom