Often we get queries/requests on how someone can help with the documentation, and how they can set up the docs application on their local machine so as to see changes immediately on their screen before issuing a pull request with their changes.
This blog post outlines how to set up our docs app and how you can help with the documentation effort.
Our documentation is split into two repositories:
- Docs App. This repo contains the application that handles our documentation (templates, CSS, etc.).
- Docs. This repo contains the actual articles that are shown on screen (content).
These repositories have been set up to work together to offer an easy way to set up and maintain the documentation.
docs repository has also been integrated with Crowdin, which handles all the translation efforts of our documentation.
So you want to set up the docs application to have the documents application running on your local machine. Great! The steps are:
- Fork the
- Fork the
- Clone the
docs-appto your machine.
- Install nanobox if you don’t have it
- Setup the
- Setup the app using nanobox
- Run the
- Run the app with nanobox
- Launch the app on your browser :)
Fork the repositories
If you haven’t done so already, fork the repositories from the phalcon github organization page https://github.com/phalcon. You will need the
In a suitable location on your machine clone the
docs-app repository (the fork)
$ git clone [email protected]:niden/docs-app
NOTE Your repository URL will be different than the above command
If you haven’t done so already, visit nanobox.io and download and install the application. It will ask you some basic questions (usually we use Docker as the engine instead of Virtualbox) as part of its setup. If you don’t meet the following requirements you should use VirtualBox.
- OS X 10.10.3 Yosemite or later
- Windows https://en.wikipedia.org/wiki/Hyper-V#Windows_Server_2008_R2
- Linux Version 3.10 or higher of the Linux kernel.
docs-app folder (or wherever you have cloned the
docs-app repository), make a copy of the
.env.example file and rename it to
.env. Open the file and edit:
APP_URLentry with a local domain. In this example we use
DOCS_REPOentry to your fork of the
docsrepo. For example it will be something like this:
Setup the app using nanobox
In your folder (where you cloned
docs-app) run the following command in a terminal:
$ nanobox run
After a while you will see something like this:
$ nanobox run Preparing environment : docs-app (local) : ... Preparing environment : ... Building dev environment : ✓ Starting docker container ✓ Configuring ** ********* *************** Your command will run in an isolated Linux container :: ********* :: Code changes in either the container or desktop are mirrored " ::: *** ::: " ------------------------------------------------------------ "" ::: "" If you run a server, access it at >> 172.18.0.4 "" " "" "
Once nanobox finishes its tasks, you will be “inside” the container. Your prompt will be:
In the same terminal, (root folder of
docs-app) run the
This script will start cloning the
docs repository branches needed under the
./docs folder of your
docs-app application (mind boggling - too many
docs! :D). The output on the terminal will provide information about the process.
exit to exit the container.
Run the following command to create a
hosts entry for your environment so that you can use the local domain:
$ nanobox dns add local docs.phalcon.ld
This command will be different in your system, depending on the name you chose for your local domain.
Run the app with nanobox
Run the following command:
$ nanobox run php-server
Launch the app in your browser
http://docs.phalcon.ld URL in your browser and voila!!!
If you wish to make changes to the application (
docs-app), stylesheets or layout, feel free to do so and issue a pull request in the
docs-app Phalcon repository.
You can also help with some of the English text located in the
en folder under each version folder (
docs/3.1/en, etc.). These changes will be sent to the
docs Phalcon repository.
Changes to a docs file (markdown) in any language other than English will not be accepted.
For languages other than English, you will need to use Crowdin Project for the documentation:
The translated strings will be brought into the documentation via pull requests from Crowdin.
<3 Phalcon Team