Issues on the public RCloud instance at http::/rcloud.social
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
community
css
doc
documentation
fonts
gallery
html
images
js
tryit
tutorials
Makefile
Makefile.mk
README.pd
body.html
empty.pd
favicon.ico
index.css
make_template.sh
topic.mk

README.pd

This document describes the organization and build process for the RCloud Web-site.

The document dinstinguished between two different types of site-file.

1) Topic files which are used to contain the content for the topics selected
from the sites main menu. (e.g. Community, Try It!, Gallery, etc)

2) External documentation files which are maintained sepearate from the site and contain
the user guide and release notes for each version of the RCloud distribution.


RCloud Web-site source tree
---------------------------

This table gives the key elemnts of the source tree.  

--------------------------------------------------------------------------------------------------
Folder                        Description
----------------------------- ---------------------------------------------------------------------
community                     'Community' topic folder

documentation                 'Documentation' topic folder

documentation/doc.mk          Each version documentation Makefile.

gallery                       'Gallery' topic folder

tryit                         'Try It' topic folder

tutorials                     'Tutorials' topic folder

css                           CSS files used by all topics

images                        Images used by topics 

js                            Global Javascript files used by the global header and footer code

html                          Common HTML files (header,footer,Pandoc template) used
                              by all of the topic pages.
		     
html/template.html5           Default Pandoc topic template.

html/head_template.html       Pandoc template used to generate the <head> contents for
                              all topic pages.  See the Notes section for more
			      about this file

html/body_top_template.html   HTML used to create the header and navigation controls
                              for all of the topic pages.  Modifying this file will
			      change the top menu throughout the site.

html/body_bottom_templatehtml HTML used to create the footer for topic pages.
			      Modifying this file will change the site footer
			      throughout the site.
			
favicon.ico                   Sites favicon

empty.pd                      An empty file.

body.html                     <body> content for the site main page (rcloud.social/index.html)

index.css                     CSS file referenced by rcloud.social/index.html.

topic.mk                      Makefile template used to generate the topic pages from markdown.

Makefile.mk                   Makefile used to create rcloud.social/index.html.

Makefile                      Master make file.
---------------------------------------------------------------------------------------------



Each topic source folder contains a subset of the following source files.

--------------------------------------------------------------------------------
File             Description
---------------- ---------------------------------------------------------------
Makefile         Topic specific Makefile.  This file includes 
		 'topic.mk' in the root source directory.  Each topic
		 however may customize 'topic.mk' by setting variables or
		 including  'make' commands within it.
		 

index.pd         (optional) Topic markdown file used to create 'index.html'
		 for this topic.  If this file does not exist then 'body.html'
		 must be provided.
		 
body.html 	 (optional) Topic HTML file used to populate the <body></body>
                 of 'index.html'. If this file does not exist then 'index.pd'
		 must be provided.
		 
index.css        Topic specific CSS file that is referenced from the
		 header of 'index.html'.  Note that this file is not
		 optional. If no local CSS style is necessary create
		 a blank CSS file.  
		 
template.html5   (optional) Topic specific Pandoc template file.
		 If this file does not exist then html/index_template.html5
		 is used as the Pandoc template file.
		 See 'tutorials' for an example of the use of a topic specific
		 template file.
		 
index.yaml	 (Optional) Some topics are simplified by drawing data
                 from a YAML source.  See 'gallery'.
--------------------------------------------------------------------------------

The site build process is resonsible for generating the site folder tree,
converting all of the markdown files to HTML, and populating the output tree
with the HTML and auxilliary files (CSS,Javascript, images, etc).

The build process can be broken into two stages. The first stage
builds the topic pages and the second state builds the external documenation.

The topic page build process produces two output files,
'topic/index.html' and 'topic/index.css', for each topic folder.

The external documenation build process produces a user guide
(documenation/doc/x.y/guidocs/doc.html) and release notes
(documenation/doc/x.y/whatnew/doc.html) for each release version.
Where x.y refers to the release version number.

Before building the site pull a current copy of this repository (e.g., git pull); the doc
 directory in this repository contains all the markdown documentation files.

~~~~
cd ../path/to/rcloud
git pull
~~~~


Build the site from command line as follows:

~~~~
cd ~/site_src  # Where site_src is the folder with the master Makefile.

# OUT_DIR  = site output location
# DOC_DIR  = path to the external documetation folder. This is the
# folder containing the version folders (e.g. 1.3,1.4, etc)
make OUT_DIR=~/temp/foo DOC_DIR=path/to/rcloud/doc 
~~~~

Remove intermediate files (but not output files).
Some intermediate files are left in the source tree and this is a fast way
to delete.
~~~~
make  clean
~~~~

Remove intermeditate and output files. Note that this will not delete the
output tree but will remove all files from it.
~~~~
make OUT_DIR=~/temp/foo clean-all
~~~~


Notes
-----
1) The build instructions for each of the the topic pages are contained in
topic/Makefile.  Each topic/Makefile is a thin wrapper around topic.mk.

2) The build instructions for the external documention is in documention/doc.mk.

3) The sites main page is built by ./Makefile.mk which, like the topic/Makefiles
is a wrapper around topic.mk.

4) html/*_template.html files are  Pandoc template used to generate the header
and footer for all HTML files (topic and external documentation) generated
by the build process. The templates contain references to CSS and Javascript files
contained in ./css and ./js as well as 'href' links to other files in the output tree.
Templates are required to create the this content
because the CSS,Javascript, and 'href' references, must reference the files irregardless of
their own position in the output tree.  For example a file in the documentation folder
can reference a CSS folder like this

~~~~
  <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css">
~~~~

but a documentation file in ./documenation/doc/1.3/guidocs/doc.html would need to
reference it like this:

~~~~
  <link rel="stylesheet" href="../../../../css/bootstrap.min.css" type="text/css">
~~~~

This problem is solved, in topic.mk, and doc.mk by generating intermediate
files (e.g. head.html,body_top.html,body_bottom.html) with the path to the referenced files set according to the
location of the generated HTML file.  The generated file is then included in the
final output file using the Pandoc options like `--include-in-header=head.html`.