README.md 8.23 KB
Newer Older
Michael McAndrew's avatar
Michael McAndrew committed
1
# CiviCRM documentation infrastructure
Michael McAndrew's avatar
Michael McAndrew committed
2

3
This repository holds source code for the *infrastructure* CiviCRM uses to host and update various documentation books built with [MkDocs](http://mkdocs.org/) and published to [docs.civicrm.org](https://docs.civicrm.org).
Michael McAndrew's avatar
Michael McAndrew committed
4

5
You may also wish to:
Michael McAndrew's avatar
Michael McAndrew committed
6

7 8
- [*Read* these documentation books](https://civicrm.org/documentation) *(and other sources of documentation)*
- [*Contribute* to documentation content](https://docs.civicrm.org/dev/en/master/documentation/)
9

Michael McAndrew's avatar
Michael McAndrew committed
10

11
## Documentation books
Michael McAndrew's avatar
Michael McAndrew committed
12

13
CiviCRM documentation is organised into various *books*. The content for a book is written in [markdown](https://docs.civicrm.org/dev/en/master/markdownrules/) and stored in a git repository (for example https://github.com/civicrm/civicrm-user-guide ). If a book is translated into different languages, then a separate repository is used for each language. If required, different *versions* of a book can be made by creating different *branches* in a repository. See *Defining books* below for more information.
14

15
## Defining a new book
Michael McAndrew's avatar
Michael McAndrew committed
16

17
Books are defined with a Yaml configuration file. To define a new book, create a `.yml` file and add it to the `app/config/books/` directory of this repository.
Michael McAndrew's avatar
Michael McAndrew committed
18

Michael McAndrew's avatar
Michael McAndrew committed
19
The config file defines the name of the book, the repository that contains the source code, and the **languages** that the book is available in, with a repository for each language. For each language, the configuration file defines:
Michael McAndrew's avatar
Michael McAndrew committed
20 21 22

* which **edition** of the book should be considered **stable**
* where to find the **latest** edits to the book
23
* a history of book **editions** of the book (these will be publicly listed at https://docs.civicrm.org/).
Michael McAndrew's avatar
Michael McAndrew committed
24

25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
If you would like to be notified by email whenever an update to a book is published, you can add your email to the notify list.

**Example book definition:**
```yml
name: User guide
description: Aimed at day to day users of CiviCRM.
langs:
    en:
        repo: 'https://github.com/michaelmcandrew/civicrm-user-guide'
        latest: master
        stable: 4.7
        history:
            - 4.6
            - 4.5
            - 4.4
        notify:
            michael@civicrm.org # will be notified when documentation is published (as well as any emails mentioned in commits)
    ca:
        repo: 'https://github.com/babu-cat/civicrm-user-guide-ca'
        latest: master
        # stable: master (will not be published)
```

48
## Publishing updates to a book
49

50
Books are automatically published when the corresponding branch is updated their repository. This is typically achieved 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.
51

52
### Setting up automatic publishing
Michael McAndrew's avatar
Michael McAndrew committed
53

54
#### GitHub
55
Auto updates are configured via webhooks within the repository on GitHub. You will need to be an owner (not just a collaborator) of the repository in order to perform these steps.
Michael McAndrew's avatar
Michael McAndrew committed
56

57 58 59 60 61 62 63 64 65 66 67
1. Go to `https://github.com/[user-or-group-name]/[repo-name]/settings/hooks/new`
2. Set the **Payload URL** to https://docs.civicrm.org/admin/listen
3. Set the **Content type** to 'application/json'
4. Set **Which events would you like to trigger this webhook?** to 'Let me select individual events' and select 'Pull request' and 'Push' (since these are the only events that should trigger an update)

#### GitLab

1. Go to `https://lab.civicrm.org/[user-or-group-name]/[repo-name]/settings/integrations
2. Set the **URL** to https://docs.civicrm.org/admin/listen
3. Set the **Trigger** to 'Push events' and 'Tag push events'.

68

69
### Manual publishing
Michael McAndrew's avatar
Michael McAndrew committed
70

71
If required, a book can be manually updated by calling a URL in the following format.
Michael McAndrew's avatar
Michael McAndrew committed
72

73 74
```text
https://docs.civicrm.org/admin/publish/{book}/{lang}/{branch}
Michael McAndrew's avatar
Michael McAndrew committed
75 76
```

77 78 79
* `{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.
Michael McAndrew's avatar
Michael McAndrew committed
80

Michael McAndrew's avatar
Michael McAndrew committed
81

82 83
## Installing a local copy of the docs infrastructure

84 85 86 87 88 89 90
### Docker

The repo includes a dockerfile which you can use to create a container which has everything needed to run the application.

To build the container and install composer dependencies just run (from the project directory):

```bash
91 92
docker build -t docs-publisher .
docker run --rm -v $PWD:/var/www docs-publisher composer install --working-dir=/var/www
93 94 95 96 97
```

And then to run it:

```bash
98
docker run --rm -v $PWD:/var/www -p 8080:8080 docs-publisher
99 100 101 102
```

You might want to change the first 8080 in the port argument if you've already got something listening on that port. 

103
The `nginx` user in the container will need to be able to write to these directories.
104

105
```bash
106
sudo chmod -R a+rw var/cache var/logs/ web/dev/ var/repos/
107
```
108 109 110 111 112

You should be able to see the app at http://localhost:8080.

### On your host machine

113 114
**Note**: the following steps are only useful and necessary for people looking after CiviCRM's documentation *infrastructure*. You don't need to do this if you just want to [contribute to documentation content](https://docs.civicrm.org/dev/en/master/documentation/).

115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
1. Install the pre-requisites:
  **Note**: the example commands have been tested on Ubuntu 16.04 and 18.04.
   * [nginx](https://nginx.org):
     ``` bash
     sudo apt install nginx
     ```
   * [mysql](https://mysql.com):
     ``` bash
     sudo apt install mysql-server
     ```
   * [php 7.1](https://php.net):
     ``` bash
     sudo apt install software-properties-common
     sudo add-apt-repository ppa:ondrej/php
     sudo apt update
     sudo apt install php7.1-fpm php7.1-mcrypt php7.1-mbstring php7.1-cli php7.1-xml php7.1-mysql php7.1-gd php7.1-imagick php7.1-recode php7.1-tidy php7.1-xmlrpc
     ```
   * [pip](https://packaging.python.org/en/latest/install_requirements_linux/#installing-pip-setuptools-wheel-with-linux-package-managers):
     ``` bash
     sudo apt install python-pip
     ```
   * [composer](https://getcomposer.org)
     ``` bash
     sudo apt install composer
     ```
   * [mkdocs](https://mkdocs.org) *CiviCRM Docs Publisher expects MkDocs version 0.16.x*
     ``` bash
     sudo -H pip install mkdocs==0.16.3
     sudo -H pip install mkdocs-material==1.4.1
     sudo -H pip install pygments==2.2.0
     sudo -H pip install pymdown-extensions==2.0
     ```
     **Note**: Ensure that MkDocs is installed as root so that it can be accessed from the src/publish.php script (typically invoked as https://docs.civicrm.org/publish.php)*

2. clone this repository to somewhere like /var/www/civicrm-docs and run `composer install`

    ```bash
    git clone https://lab.civicrm.org/documentation/docs-publisher.git /var/www/civicrm-docs
    cd /var/www/civicrm-docs
    composer install
    ```

3. Set appropriate permissions on web/static

4. Update the nginx configuration file to point to the php7.1-fpm socket and fix the root.

MikeyMJCO's avatar
MikeyMJCO committed
161
    [- root /var/www/web; -]  
162 163 164 165 166 167 168 169 170 171 172
    [+ root /var/www/civicrm-docs/web; +]

    [- fastcgi_pass unix:/var/run/php-fpm.sock; -]  
    [+ fastcgi_pass unix:/var/run/php/php7.1-fpm.sock; +]

5. Configure the nginx virtual host

    ```bash
    cd /etc/nginx/sites-enabled
    ln -s /var/www/civicrm-docs/app/config/civicrm-docs.conf civicrm-docs
    ```
173

174
6. Reload your nginx config and you should be up and running.
175

176 177 178 179 180 181 182 183 184 185 186 187
### Debugging

You will need xdebug installed and configured to debug from your IDE. In this case
we assume you're using PHPStorm. 

The docker image comes with xdebug pre-installed and configured. From there the steps you need to take to get it working are:

- From "Settings > Languages and Frameworks > PHP > Debug" change the xdebug port to 9000
- From "Settings > Languages and Frameworks > PHP > Servers" add a new server with any name, host of "localhost", port of 8080. 
- In the same screen enable path mappings and map the project directory to "/var/www" under "Absolute path on the server"
- Install the xdebug helper for [chrome](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc?hl=en) or [firefox](https://addons.mozilla.org/en-gb/firefox/addon/the-easiest-xdebug/), setting the IDE key to "PHPSTORM" if necessary.
- Enable the xdebug helper, put a breakpoint somewhere in web/app_dev.php and visit http://localhost:8080 and the debugged should open PHPStorm