tig12
/
tigsite
1
0
Fork 0
Code Issues 0 Pull Requests 0 Releases 0 Wiki Activity
Browse Source

Add documentation

master
Thierry 4 years ago
parent
8619adc2b9
commit
dd13b359f8
5 changed files with 338 additions and 10 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +6
    -0
      README
  2. +143
    -5
      docs/index.html
  3. +186
    -0
      docs/static/style.css
  4. +1
    -3
      src/commands/replaceHtml.php
  5. +2
    -2
      src/run-tigsite.php

+ 6
- 0
README View File

@@ -1 +1,7 @@
Tools to manage tig12.net

Usage :
cd src
php run-tigsite.php

Follow the instructions of the error message

+ 143
- 5
docs/index.html View File

@@ -1,9 +1,147 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>tigsite</title>
<meta name="description" content="A tool to assist the development of a static site">
<link rel="shortcut icon" href="favicon.png" type="image/x-icon">
<link rel="copyright" href="http://www.gnu.org/copyleft/gpl.html"/>
<link rel="stylesheet" href="static/style.css" type="text/css">
</head>

<body>

<header>
<h1>tigsite</h1>
<div class="intro">
This tool assists the development of a web site containing static pages.
<br>It was developed to help writing <a href="https://tig12.net">tig12.net</a>
</div>
</header>

<article>

<h2>Site config.yml</h2>
- 'location' : absolute path to directory containing the files to process.
- 'exclude' (optional) : array of strings containing regular expressions
of relative paths to files to exclude from processing.
Defaults to an empty array
<!-- ********************************************************************************* -->
<h2>Overview</h2>

The tool is run on the command line :
<pre>
cd src/
php run-tigsite.php &lt;site> &lt;command>
</pre>

<code>&lt;site></code> must be the name of a sub-directory of <code>sites/</code>.
<br><code>&lt;command></code> must be the name of a yaml file inside site's <code>commands/</code> sub-directory.
<br>
<br>For example,
<pre>php run-tigsite.php tig12.net replace-footer</pre>

corresponds to this hierarchy :

<pre>
sites/
└── tig12.net
├── commands
│   └── replace-footer.yml
└── config.yml
</pre>

<ul>
<li>The command name specified does not include the "<code>.yml</code>" extension.</li>
<li>
Commands can be organized in subdirectories.
<br>For example,
<pre>php run-tigsite.php tig12.net asides/replace-footer</pre>
corresponds to
<pre>
sites/
└── tig12.net
├── commands
│   └── asides
│       └── replace-footer.yml
└── config.yml
</pre>
</li>
</ul>



<!-- ********************************************************************************* -->
<h2>Site directories</h2>
Each site managed by this tool must correspond to a sub-directory of <code>sites/</code> and have this structure :
<pre>
sites/
└── mysite.org
├── commands/
└── config.yml
</pre>

<!-- ************************************* -->
<h3>config.yml</h3>

Configuration file containing iniformation used by all commands related to the site
<br>
<br>Example :
<pre>
location: /pat/to/the/site/web
exclude:
- .git
- .gitignore
- static
</pre>

<table class="wikitable">
<tr><th>Directive</th><th></th><th>Description</th></tr>
<tr>
<td>location</td>
<td>Required</td>
<td>Absolute path to the root directory of the site.</td>
</tr>
<tr>
<td>exclude</td>
<td>Optional</td>
<td>
Array of strings containing regular expressions of relative paths to files to exclude from processing.
<br>Defaults to an empty array
</td>
</tr>
</table>


<!-- ********************************************************************************* -->
<h2>Commands</h2>

The yaml files located in <code>sites/&lt;my-site>/commands/</code> are used to specify :
<br>- which command is used
<br>- the parameters passed to the command.
<br>
<br>The available commands are located in <code>src/commands</code>.
<br>All commands implement the interface <code>Command</code>, which define a unique method :
<br><code>public static function execute($params)</code>

<br>
<br>Example of a command file :
<pre>
commandClass: replaceHtml
before: '&lt;footer>'
after: '&lt;/footer>'
</pre>

In a command file, the unique required directive is <code><b>commandClass</b></code>
<br>The other directives depend on the command ; they are passed as parameters to the command.

<!-- ************************************* -->
<h3>insertHtml</h3>
See code documentation in <code>src/commands/insertHtml.php</code>.

<!-- ************************************* -->
<h3>replaceHtml</h3>
See code documentation in <code>src/commands/replaceHtml.php</code>.

</article>

</body>
</html>

<!-- ************************************* -->
<!-- ********************************************************************************* -->

+ 186
- 0
docs/static/style.css View File

@@ -0,0 +1,186 @@

/* ================ General styles ================ */
body{
margin:0;
margin-bottom:1rem;
padding:0.5rem;
background:#eee;
font-family:Arial,Helvetica,sans-serif;
font-size:1.4rem;
}

a{text-decoration:none;}

pre{margin:1rem 2rem; background:lightgrey; font-size:1rem; padding:0.5rem;}
pre.normal{background:none;}
code.color{background:lightgrey;}
.pre{white-space:pre;}

img{display: block; background:white;}
img.center{border:none;margin:auto;}

ul.spaced li,ol.spaced li{padding-bottom:0.8rem;}
ul.naked li,ol.naked li{list-style-type:none;}

table.border{border-collapse:collapse;}
table.border td{border: 1px solid #a2a9b1;}

cite{
display:block;
margin:1rem;
}

blockquote{
display:block;
border:1px solid grey;
padding:5px;
margin:1rem;
font-family:DejaVu,serif;
background:#fee;
}

/* ================ Site layout ================ */
.flex-wrap{
display:flex;
flex-wrap:wrap;
}
aside ul{padding:0;}
aside li{list-style:none;}

/* ================ Headings ================ */
h1{
width:100%;
margin:auto;
text-align:center;
font-size:2.5em;
font-weight:bold;
padding:0.3rem;
margin-bottom:1rem;
}
h1 .subtitle{font-size:0.8em;}
h2{font-size:2rem;}
h3{font-size:1.5rem;}


/* ================ Navigation ================ */

.prevnext{
font-family:DejaVu,serif;
position: fixed; top:0px; right:0px;
margin:1rem;
width:75px; height:40px
}
.prevnext a{
display:inline-block;
position:fixed;
width:40px; height:40px;
text-decoration:none;
font-weight:bolder;
font-size:2rem;
}
.prevnext a.index{top:0px; right:10px; font-size:0.5rem;}
.prevnext a.top{top:0px; right:40px;}
.prevnext a.prev{top:25px; right:75px;}
.prevnext a.next{top:25px; right:5px;}

/* table of content */
.toc{font-family:Arial,Helvetica,sans-serif;}
.toc ul{list-style-type:none;}
.toc{padding:0;}
.toc>ul>li>a{font-weight:bold;}


/* ================ Particular elements ================ */

.warning{
width:50%;
padding:.5rem;
margin:.5rem;
background:gold;
border:1px solid grey;
}

.intro{
font-size:1.2em;
margin:1rem 0 1rem 2rem;
}

.exo{
font-size:1rem;
border:1px solid grey;
padding:0.6rem 1rem;;
background:lightyellow;
margin:1rem;
}
.exo ul{margin:0;}

table.wikitable{
border-collapse:collapse;
}
table.wikitable > tr > th, table.wikitable > * > tr > th {
/* background-color: #eaecf0; */
background-color: lightblue;
text-align: center;
vertical-align:top;
}
table.wikitable > tr > th, table.wikitable > tr > td, table.wikitable > * > tr > th, table.wikitable > * > tr > td {
border: 1px solid #a2a9b1;
padding: 0.2rem 0.4rem;
vertical-align:top;
}
table.wikitable tr td code{
background:none;
}


/* ================ Style shortcuts ================ */

.inline-block{display:inline-block;}
.block{display:block;}

.arial{font-family:Arial,Helvetica,sans-serif;}
.courier{font-family:"Courier New",Courier,monospace;}
.dejavu{font-family:DejaVu,serif;}

.bold{font-weight:bold;}

.center{text-align:center;}

.border{border:1px solid grey;}

.margin{margin:1rem;}
.margin0{margin:0;}
.margin2{margin:2rem;}
.margin-top{margin-top:1rem;}
.margin-top0{margin-top:0;}
.margin-left{margin-left:1rem;}
.margin-left0{margin-left:0;}
.margin-bottom{margin-bottom:1rem;}
.margin-bottom0{margin-bottom:0;}
.margin-right{margin-right:1rem;}
.margin-right0{margin-right:0;}

.padding{padding:1rem;}
.padding0{padding:0;}
.padding2{padding:2rem;}
.padding-top{padding-top:1rem;}
.padding-top0{padding-top:0;}
.padding-left{padding-left:1rem;}
.padding-left0{padding-left:0;}
.padding-bottom{padding-bottom:1rem;}
.padding-bottom0{padding-bottom:0;}
.padding-right{padding-right:1em;}
.padding-right0{padding-right:0;}

.big1{font-size:1.1rem;}
.big2{font-size:1.2rem;}
.big3{font-size:1.3rem;}
.big4{font-size:1.4rem;}
.big20{font-size:2rem;}
.big30{font-size:3rem;}
.big40{font-size:4rem;}

.small9{font-size:.9rem;}
.small8{font-size:.8rem;}
.small7{font-size:.7rem;}
.small6{font-size:.6rem;}

+ 1
- 3
src/commands/replaceHtml.php View File

@@ -21,6 +21,7 @@ class replaceHtml implements Command {
the new html code to insert between 'before' and 'after'.
- 'replacement-string' : string containing the new html code to insert between 'before' and 'after'.
NOTE : 'command' must contain 'replacement-file' or 'replacement-string' but not both.
- 'exclude' : array of files that must not be concerned by replacement.
@throws Exception in case of bad parameter
@todo Add parameters "config-file" and "command-file" (only useful for messages in parameter checking)
@@ -81,13 +82,10 @@ class replaceHtml implements Command {
echo "processing {$files[$i]}\n";
$subject = file_get_contents($files[$i]);
$replace2 = expandVariables::expand($replace, ['root-dir' => $params['site']['location'], 'current-file' => $files[$i]]);
//echo "$replace2\n";
//continue;
$new = preg_replace($pattern, $replace2, $subject, -1, $count);
if($count == 0){
continue;
}
//echo "$new\n"; exit;
file_put_contents($files[$i], $new);
}


+ 2
- 2
src/run-tigsite.php View File

@@ -20,8 +20,8 @@ Usage :
<site> : must be a sub-directory of sites/
<action> : must correspond to a yaml file of sites/<site>/commands/
Example :
php {$argv[0]} tig12.net updatefooter # Adds a footer in alll site pages
Uses the command file sites/tig12.net/commands/addfooter.yml
php {$argv[0]} tig12.net replace-footer # Updates the footer of all site pages
Uses the command file sites/tig12.net/commands/replace-footer.yml

USAGE;



Write Preview
Loading…
Cancel
Save