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.