From 311b90c42d74eee81508e8fe6546746b40dc3164 Mon Sep 17 00:00:00 2001 From: Clemens Tolboom Date: Sun, 8 Jun 2014 10:33:58 +0200 Subject: [PATCH] The Testing Documentation section is unclear. I installed `Sphinx` then did the `git submodules` next generated the docs thus skipping the `bash install.sh` ``` * Install `Sphinx`_; * Install the Sphinx extensions using git submodules: ``git submodule update --init``; * (Optionally) Install the bundle docs and CMF docs: ``bash install.sh``; * Run ``make html`` and view the generated HTML in the ``build`` directory. ``` It is unclear what to expect after each step. Opening ie `$ open _build/html/cookbook/controller/error_pages.html` it does not look at all similar to http://symfony.com/doc/current/cookbook/controller/error_pages.html So I ran `bash install.sh` expecting that should do it. Nope. I would propose the following changes: - [ ] Add text about test sphinx is already installed. - [ ] We should explain how the build will look like. - [ ] We should explain why `bash install.sh` is optional. - [ ] Tell about the additional _ext directory and how not to add it to the PR. --- contributing/documentation/format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 491d27df407..ecb2240b5a8 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -163,7 +163,7 @@ Testing Documentation To test documentation before a commit: -* Install `Sphinx`_; +* Check for sphinx : ``sphinx-build --version``. If not available install `Sphinx`_; * Install the Sphinx extensions using git submodules: ``git submodule update --init``; * (Optionally) Install the bundle docs and CMF docs: ``bash install.sh``; * Run ``make html`` and view the generated HTML in the ``build`` directory.