Documentation Template & Style Guide

Documentation is a critical part of the city-wide 3d model architecture. Users that download modules for their own use will probably also want to fork the documentation related to the components because the on-line documentation at citySchema.org is going to evolve and become out of sync with static local versions. Furthermore, users who make their own improvements and customizations to the architecture and tools will want to modify the documentation.

The documentation that you are looking at now is designed to be simple and to be completely functional when rendered from a plain file-system without the mediation of a web server. It is based on html, css and javascript.

Topic Index

• Basic Styling
• Slide Shows
• Figures
• Tables
• Controlling new Tabs
• Colored Text Blocks

Basic Styling

This page describes and demonstrates the basic elements that are accommodated by the docutree.css

Slide Shows

The script, slideshow_pbc.js looks for any div with class="slideshow: and turns it into a slideshow with lots of features as you can see, bwlow.

The slideshow div has to contain subdivisions that are class="slideshow_container" with more subdivisions as shown below:

The value for daya-playpaused should be either "playing" or "paused".

  <!-- Slideshow container -->
  <div id="moreslides" class="slideshow in-page" 
  data-imgheight = "250px" 
  data-title = "" 
  data-playpaused = "paused" >
  <div class="slidecontainer" data-title="Wide Image" data-caption="Away up to tree-line.">
    <div class="slide"><img src="./images/wide.jpg" ></div>
    <div class="caption"><p>Now is the time for all good men to come to the Wide Image.  
      Lets make this a very long line so that we can see the wrap-around effect..</p>
      <p>And then there was that other time
      <p>But lets focus on right now.
      <p>OK?  OK!
    </div>
    <div class="learnmore"><a href='#funfact'>Learn More about wide images</a></div></div>
  <div class="slidecontainer" data-title="Tall Image" >
    <div class="slide"> <img src="./images/tall.jpg"></div>
    <div class="caption"><p>That image is mightty tall, but maxes out at 1005 .</p></div>
    <div class="learnmore"><a href='#funfact'>Learn More about Tall Images</a></div>
    </div>
  </div> <!-- Closes moreslides-->

Another Slideshow with no title and Captions

If no captions are included in slide containers, then the slideshow element is more compact. Likewise with the title.

---

Headings with IDs Are Referenced with Scroll-To Animation

The html declaration of the heading above has an id attribute set as id="early". This ID can be addressed as an internal link within the page. For example, it is referred to as a href="../template/index.htm#early" in other pages and most importantly, in the list of "verses" that falls under the chapter, Documentation Template in the navigational sidebar.

Figures: Left, Right and Middle

The docutree.css has three types of figures. The one on the right uses the following html:

  <figure class="right">
  <img src="images/tall.jpg">
  <figcaption>Fig Right Caption</figcaption>
  </figure>
  

Makes a right-justified image.

Notice that the heading comes after the image in the html. This avoids an apparent vacant space above the image.

Normally, there would be plenty of text that pertains to the image, to fill up the half-width column on the left-hand side of the figure. If not, you can always start the next thing with a style="clear: both;", as we do with the heading,below.

Another Internal Link

The link above has id="late". It is linked in the sidebar table of contents. It demonstrates the smooth scroll effect.

Notice also that the style="clear: both" causes it to slip past the right-hand image to the next clear spot on the page.

The Middle Figure

Below this text, you will see the rendering of the following code:

  <figure class="middle">
  < src="images/wide.jpg">
  <figcaption>Fig Middle Caption</figcaption>
  </figure>
  

The next image uses the middle figure with the image class="triptic". Coded like so:

    <figure class="middle">
      <div class="middleflex">
        <img src="images/tall.jpg">
        <img src="images/tall.jpg">
        <img src="images/tall.jpg">
      </div>
    <figcaption>Fig Middle Caption</figcaption>
    </figure>
        

The Dictionary Table Style

Tables with class="dictionary look like this.

Heading 1	Heading 2
Row 1	Col 2
Row 1	Col 2

Controlling new Tabs

Some pages should be opened n specific new tabs as they may be useful refernce info related to other pages. We don;t want tabs to proliferate, however. So, for pages of a specific sort, we dlivberately want to replace other pages of the same sort in a particular tab.

• target="datadict": Data dictionary at bottom of the Model Collection Page
• target="metadata": A metadata page from the repo/catalog.
• target="download": The tiled download page from the repo/catalog.
• target="index": Documentation Index page from the repo/catalog.
• target="arcdoc": link to software documentation.
• target="github": link to a location in github.
• target="outboard": Link to a reference page outside of citySchema.org.

Feature Blocks

High-order conceptual ideas are discussed in the plain text.

Feature blocks help to break out other sorts of ideas.

More Text

Then as things roll along, there is usually more conceptual description. But before long, there might be a need for another sort of sidebar discussion. These are topics that may be a zoom-in or a zoom-out. These may be ideas that get linked to from other documents. These sidebars get a gold box but with the same bluish text.

Typically, the page would have some more text that closes up the big idea. Maybe providing pointers about were else to go.