Commit 55823bb1 authored by Michael McAndrew's avatar Michael McAndrew

updated readme and some tweaks to get it ready to deploy

parent 6cf49582
......@@ -14,5 +14,9 @@
!var/SymfonyRequirements.php
/vendor/
/web/bundles/
/web/static
/web/static/*
!/web/static/css
#not sure how else to ensure that the following two files aren't deployed on prod
/web/app_dev.php
/web/config.php
......@@ -11,57 +11,35 @@ Editions of books typically map to versions of CiviCRM (or extensions that they
See https://civicrm.org/improve-documentation for how to get started contributing to our documentation. If you have any questions about how stuff works, or how to start contributing, please join the [documentation mailing list](http://lists.civicrm.org/lists/info/civicrm-docs) and email the list with your question. We'll be very glad to help you get going.
## Publishing books
## Accessing documentation
All books are published at https://docs.civicrm.org/[name]/
CiviCRM documentation is currently found in many different sources. Our long term vision is to have it all published at https://docs.civicrm.org/.
By default, a URL in the above format will redirect to https://docs.civicrm.org/[name]/en/stable.
Documentation is organised into books, which are accessible at URLs as follows https://docs.civicrm.org/[name]/ By default, a URL in the above format will redirect to https://docs.civicrm.org/[name]/en/stable which shows the latest stable documentation. The very latest documentation (which may be incomplete / unfinished) can be accessed at https://docs.civicrm.org/[name]/en/stable.
Some time in the near future, books will automatically be updated when the corresponding branch is updated in the repository.
## Updating documentation
Until that happens, the update process can be manually triggered by calling a URL in the following format:
Books are auto be updated when the corresponding branch is updated their repository. This is typically acheived by making edits and submitting a pull request. Any emails listed in the commits that are submitted as part of the pull request will receive an email with a summary of the update process.
https://docs.civicrm.org/publish.php?book=user&branch=master&lang=en
If required, a book can be manually updated by calling a URL in the following format: https://docs.civicrm.org/admin/publish/{book}/{en}/{branch}.
With parameters set as follows:
* **book**: the name of the book - as per configuration file in the conf/books directory.
* **lang**: the language that you want to publish - as defined in the configuration file.
* **branch**: the name of the branch that you want to publish - needs to be a branch in the repository for that language.
### Trouble shooting the publishing process
Once the publising process is complete, any output from 'mkdocs build' (which is the process that actually creates the html) is shown on the screen.
If nothing is shown on the screen, some rudimentary logging available at https://docs.civicrm.org/log might give you a clue as to what happened.
**Tip:** Using 'view source' in your browser will show line breaks for these logs.
* {book} the name of the book - as per configuration file in the conf/books directory.
* {lang} the language that you want to publish - as defined in the configuration file.
* {branch} the name of the branch that you want to publish - needs to be a branch in the repository for that language.
## Defining books
Books are defined with a Yaml configuration file, stored in the conf/books directory of this repository.
Books are defined with a Yaml configuration file, stored in the app/config/books/ directory of this repository.
The config file lists the **languages** that the book is available in, with a repository for each language. For each language, the configuration file defines:
* which **edition** of the book should be considered **stable**
* where to find the **latest** edits to the book
* a history of book **editions** of the book (that will be publicly listed).
An example configuration file for the CiviCRM user guide ('user.yml'):
```Yaml
en:
repo: 'https://github.com/civicrm/civicrm-user-guide'
latest: master
stable: 4.7
history:
- 4.7
- 4.6
```
* a history of book **editions** of the book (these will be publicly listed at https://docs.civicrm.org/).
# Installation
**Note**: the following steps are only useful and necessary for people looking after CiviCRM's documentation infrastructure. If you want to contributing to CiviCRM's documentation, see [Contributing to documentation](#contributing-to-documentation) above.
**Note**: the following steps are only useful and necessary for people looking after CiviCRM's documentation infrastructure.. If you are want to contribute to CiviCRM's documentation, there see [Contributing to documentation](#contributing-to-documentation) above.
1) Ensure that that you have [pip](https://packaging.python.org/en/latest/install_requirements_linux/#installing-pip-setuptools-wheel-with-linux-package-managers) (for python) and [composer](https://getcomposer.org/) (for php) installed..
......@@ -81,18 +59,11 @@ $ cd /var/www/civicrm-docs
$ composer install
```
4) Run the civicrm-docs install script
```
$ cd /var/www/civicrm-docs
$ ./install.sh
```
5) Configure an nginx virtual host
```
$ cd /etc/nginx/sites-enabled
$ ln -s /var/www/civicrm-docs/conf/nginx.conf civicrm-docs
$ ln -s /var/www/civicrm-docs/app/config/nginx.conf civicrm-docs
```
6) Reload your nginx config and you should be up and running.
......@@ -101,16 +72,11 @@ $ ln -s /var/www/civicrm-docs/conf/nginx.conf civicrm-docs
* A CiviCRM theme for documentatiom
* Create a better docs homepage
* Automate creation of symlinks for latest and stable based on book.yml file
* Create history for each book based on book.yml file
* Improve nginx.conf
* Remove the trailing slash from URLs
* user|developer|etc should not be hard coded
* avoid root in location block. Might need to rethink dir structure (https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#root-inside-location-block)
* Last but not least: migrate lots of documentation (e.g. our developer and sys administrator documentation)
* Inlcuding a history for each book based on book.yml file
* Future proof documentation structure
* / - documentation home
* /user/ - user documentation for core civicrm
* /extensions/*/ - documentation for extensions (probably mostly user focused, though with possible developer and system administrator sections)
* /extensions/[extenstion_name] - documentation for extensions (probably mostly user focused, though with possible developer and system administrator sections)
* /admin/ - system administrator documentation (installation, upgrades, email server configuration)
* /dev/ - developer documentation
* Last but not least: migrate lots of documentation (e.g. our developer and sys administrator documentation)
server {
server_name docs;
root /home/michael/civicrm-docs/web/static;
location ~ ^/(admin|[[:alpha:]]+/*$|$) {
# try to serve file directly, fallback to app.php
try_files $uri /app.php$is_args$args;
}
# PROD
location ~ ^/app\.php(/|$) {
alias /home/michael/civicrm-docs/web/;
fastcgi_pass unix:/var/run/php5-fpm.sock;
fastcgi_split_path_info ^(.+\.php)(/.*)$;
include fastcgi_params;
# When you are using symlinks to link the document root to the
# current version of your application, you should pass the real
# application path instead of the path to the symlink to PHP
# FPM.
# Otherwise, PHP's OPcache may not properly detect changes to
# your PHP files (see https://github.com/zendtech/ZendOptimizerPlus/issues/126
# for more information).
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $realpath_root;
# Prevents URIs that include the front controller. This will 404:
# http://domain.tld/app.php/some-path
# Remove the internal directive to allow URIs like this
internal;
}
error_log /var/log/nginx/project_error.log;
access_log /var/log/nginx/project_access.log;
}
<?php
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Debug\Debug;
// If you don't want to setup permissions the proper way, just uncomment the following PHP line
// read http://symfony.com/doc/current/book/installation.html#checking-symfony-application-configuration-and-setup
// for more information
//umask(0000);
// This check prevents access to debug front controllers that are deployed by accident to production servers.
// Feel free to remove this, extend it, or make something more sophisticated.
if (isset($_SERVER['HTTP_CLIENT_IP'])
|| isset($_SERVER['HTTP_X_FORWARDED_FOR'])
|| !(in_array(@$_SERVER['REMOTE_ADDR'], ['127.0.0.1', 'fe80::1', '::1']) || php_sapi_name() === 'cli-server')
) {
header('HTTP/1.0 403 Forbidden');
exit('You are not allowed to access this file. Check '.basename(__FILE__).' for more information.');
}
/**
* @var Composer\Autoload\ClassLoader $loader
*/
$loader = require __DIR__.'/../app/autoload.php';
Debug::enable();
$kernel = new AppKernel('dev', true);
$kernel->loadClassCache();
$request = Request::createFromGlobals();
$response = $kernel->handle($request);
$response->send();
$kernel->terminate($request, $response);
<?php
/*
* ************** CAUTION **************
*
* DO NOT EDIT THIS FILE as it will be overridden by Composer as part of
* the installation/update process. The original file resides in the
* SensioDistributionBundle.
*
* ************** CAUTION **************
*/
if (!isset($_SERVER['HTTP_HOST'])) {
exit('This script cannot be run from the CLI. Run it from a browser.');
}
if (!in_array(@$_SERVER['REMOTE_ADDR'], array(
'127.0.0.1',
'::1',
))) {
header('HTTP/1.0 403 Forbidden');
exit('This script is only accessible from localhost.');
}
require_once dirname(__FILE__).'/../var/SymfonyRequirements.php';
$symfonyRequirements = new SymfonyRequirements();
$majorProblems = $symfonyRequirements->getFailedRequirements();
$minorProblems = $symfonyRequirements->getFailedRecommendations();
?>
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="robots" content="noindex,nofollow" />
<title>Symfony Configuration Checker</title>
<link rel="stylesheet" href="bundles/framework/css/structure.css" media="all" />
<link rel="stylesheet" href="bundles/framework/css/body.css" media="all" />
<style type="text/css">
/* styles copied from bundles/sensiodistribution/webconfigurator/css/install.css */
body {
font-size: 14px;
font-family: "Lucida Sans Unicode", "Lucida Grande", Verdana, Arial, Helvetica, sans-serif;
}
.sf-reset h1.title {
font-size: 45px;
padding-bottom: 30px;
}
.sf-reset h2 {
font-weight: bold;
color: #FFFFFF;
/* Font is reset to sans-serif (like body) */
font-family: "Lucida Sans Unicode", "Lucida Grande", Verdana, Arial, Helvetica, sans-serif;
margin-bottom: 10px;
background-color: #aacd4e;
padding: 2px 4px;
display: inline-block;
text-transform: uppercase;
}
.sf-reset ul a,
.sf-reset ul a:hover {
background: url(../images/blue-arrow.png) no-repeat right 6px;
padding-right: 10px;
}
.sf-reset ul, ol {
padding-left: 20px;
}
.sf-reset li {
padding-bottom: 18px;
}
.sf-reset ol li {
list-style-type: decimal;
}
.sf-reset ul li {
list-style-type: none;
}
.sf-reset .symfony-blocks-install {
overflow: hidden;
}
.sf-reset .symfony-install-continue {
font-size: 0.95em;
padding-left: 0;
}
.sf-reset .symfony-install-continue li {
padding-bottom: 10px;
}
.sf-reset .ok {
color: #fff;
font-family: "Lucida Sans Unicode", "Lucida Grande", Verdana, Arial, Helvetica, sans-serif;
background-color: #6d6;
padding: 10px;
margin-bottom: 20px;
}
.sf-reset .ko {
background-color: #d66;
}
.version {
text-align: right;
font-size: 10px;
margin-right: 20px;
}
.sf-reset a,
.sf-reset li a {
color: #08C;
text-decoration: none;
}
.sf-reset a:hover,
.sf-reset li a:hover {
color: #08C;
text-decoration: underline;
}
.sf-reset textarea {
padding: 7px;
}
</style>
</head>
<body>
<div id="content">
<div class="header clear-fix">
<div class="header-logo">
<img src="bundles/framework/images/logo_symfony.png" alt="Symfony" />
</div>
<div class="search">
<form method="get" action="http://symfony.com/search">
<div class="form-row">
<label for="search-id">
<img src="bundles/framework/images/grey_magnifier.png" alt="Search on Symfony website" />
</label>
<input name="q" id="search-id" type="search" placeholder="Search on Symfony website" />
<button type="submit" class="sf-button">
<span class="border-l">
<span class="border-r">
<span class="btn-bg">OK</span>
</span>
</span>
</button>
</div>
</form>
</div>
</div>
<div class="sf-reset">
<div class="block">
<div class="symfony-block-content">
<h1 class="title">Configuration Checker</h1>
<p>
This script analyzes your system to check whether is
ready to run Symfony applications.
</p>
<?php if (count($majorProblems)): ?>
<h2 class="ko">Major problems</h2>
<p>Major problems have been detected and <strong>must</strong> be fixed before continuing:</p>
<ol>
<?php foreach ($majorProblems as $problem): ?>
<li><?php echo $problem->getHelpHtml() ?></li>
<?php endforeach; ?>
</ol>
<?php endif; ?>
<?php if (count($minorProblems)): ?>
<h2>Recommendations</h2>
<p>
<?php if (count($majorProblems)): ?>Additionally, to<?php else: ?>To<?php endif; ?> enhance your Symfony experience,
it’s recommended that you fix the following:
</p>
<ol>
<?php foreach ($minorProblems as $problem): ?>
<li><?php echo $problem->getHelpHtml() ?></li>
<?php endforeach; ?>
</ol>
<?php endif; ?>
<?php if ($symfonyRequirements->hasPhpIniConfigIssue()): ?>
<p id="phpini">*
<?php if ($symfonyRequirements->getPhpIniConfigPath()): ?>
Changes to the <strong>php.ini</strong> file must be done in "<strong><?php echo $symfonyRequirements->getPhpIniConfigPath() ?></strong>".
<?php else: ?>
To change settings, create a "<strong>php.ini</strong>".
<?php endif; ?>
</p>
<?php endif; ?>
<?php if (!count($majorProblems) && !count($minorProblems)): ?>
<p class="ok">All checks passed successfully. Your system is ready to run Symfony applications.</p>
<?php endif; ?>
<ul class="symfony-install-continue">
<?php if (count($majorProblems) || count($minorProblems)): ?>
<li><a href="config.php">Re-check configuration</a></li>
<?php endif; ?>
</ul>
</div>
</div>
</div>
<div class="version">Symfony Standard Edition</div>
</div>
</body>
</html>
.message {
font-weight: bold;
}
.message-debug {
color: #cccccc;
}
.message-info {
color: #468847;
}
.message-notice {
color: #3a87ad;
}
.message-warning {
color: #c09853;
}
.message-error {
color: #f0ad4e;
}
.message-critical {
color: #ff7708;
}
.message-alert {
color: #c12a19;
}
.message-emergency {
color: #000000;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment