Contribute to Website

The source code for doctrine-project.org is completely open source and easy for you to setup locally so you can submit contributions back to the project.

Installation

First, create a fork of the repository and clone it to a directory like /data:

$ cd /data
$ git clone [email protected]:username/doctrine-website.git

Next run composer install && yarn install to install all of the dependencies.

$ cd doctrine-website
$ composer install && yarn install

Coding Standards

Copy the pre-commit hook to .git/hooks/pre-commit to ensure coding standards are maintained:

$ cp pre-commit .git/hooks/pre-commit

Configuration

Copy the config/local.yml.dist config file that came with the repository:

$ cp config/local.yml.dist config/local.yml

GitHub API

In order to build the website, you will need to configure a GitHub API key with the doctrine.website.github.http_token parameter in your config/local.yml file. You can create an API token by going to the Personal access tokens section on the GitHub website.

Algolia Search Indexes

In order to build the Algolia search indexes you will need to configure the doctrine.website.algolia.admin_api_key parameter in your config/local.yml file. This key is not distribute to anyone, is optional and is not required in order to build the website.

Edit your Hosts File

Edit your /etc/hosts file and point lcl.doctrine-project.org at your local web server. You will need to setup a virtual host in your web server and point the root directory at /data/doctrine-website/build-dev.

Sync Project Repositories

First you need to checkout or update the repositories for each project.

$ ./bin/console sync-repositories

Build Website Data

The website build process relies on data that is dynamically pulled from Git, GitHub API and YAML files in the config folder. To build the website data, run the build-website-data command.

$ ./bin/console build-website-data

Build Documentation

Now are you ready to start building the website! Build the documentation with the build-docs command.

$ ./bin/console build-docs

API Documentation

By default only the RST docs are built. You need to pass the --api option to also generate the API docs:

$ ./bin/console build-docs --api

We use Sami for generating the PHP API documentation for each project.

Search Indexes

To build the Algolia search indexes pass the --search option:

$ ./bin/console build-docs --search

You will need to have the doctrine.website.algolia.admin_api_key parameter in config/local.yml in order to update the Algolia search indexes.

Build the Website

Now you are ready to build the website for the first time:

$ ./bin/console build-website

Go take a look at lcl.doctrine-project.org and the local website should render. The built code for the website is written to /data/doctrine-website/build-dev.

Watch Frontend Assets

After the initial build you can watch for frontend asset changes to update the stylesheets.

$ npm run watch

This process will run in the foreground and recompile the assets when a change is made to them. After refreshing the browser you should see the new assets loaded.

reStructuredText

The Doctrine documentation is written in a markup language called reStructuredText (RST). It is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. The syntax is parsed by the doctrine/rst-parser library.

You can see examples of RST here.

Submitting Pull Requests

If you see something that could be improved or a bug that needs fixing, submit a pull request with the changes to doctrine/doctrine-website.

You can also take a look at the list of open issues on GitHub and look for something that needs help.