From 2081acc3c5d3f9c998bff81d4453588c7fde392d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ste=CC=81phane=20Goetz?= Date: Fri, 29 Jul 2016 23:20:01 +0200 Subject: [PATCH] Document the new command line tool --- README.md | 70 ++++++++++--------- docs/00_Getting_Started.md | 17 ++--- docs/01_Features/Live_mode.md | 6 +- docs/01_Features/Static_Site_Generation.md | 12 ++-- .../10_For_Developers/Creating_a_Processor.md | 2 +- libs/Format/Confluence/Api.php | 3 +- .../Confluence/DuplicateTitleException.php | 2 +- 7 files changed, 55 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 9958a3d..9ec4ce3 100755 --- a/README.md +++ b/README.md @@ -32,23 +32,38 @@ This is a list of sites using Daux.io: -* [Daux.io](http://daux.io) -* [Gltn - An open-source word processor webapp](http://felkerdigitalmedia.com/gltn/docs/) -* [Invade & Annex 3 - An Arma 3 Co-operative Mission](http://ia3.ahoyworld.co.uk/) -* [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee) -* [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/) -* [TrackJs](http://docs.trackjs.com) (uses a customized theme) -* [Sugoi](http://doc.sugoi.ventrux.com/) -* [wallabag](http://doc.wallabag.org/index) -* [iGeo-Topo](http://igeo-topo.fr/doc) -* [Cumulus TV: Android TV app that turns any stream/page into a Live Channel](http://cumulustv.herokuapp.com) -* [Vulkan Tutorial](https://vulkan-tutorial.com) +- With a custom theme: + * [Vulkan Tutorial](https://vulkan-tutorial.com) + * [TrackJs](http://docs.trackjs.com) +- With the default Theme + * [Daux.io](http://daux.io) + * [Gltn - An open-source word processor webapp](http://felkerdigitalmedia.com/gltn/docs/) + * [Invade & Annex 3 - An Arma 3 Co-operative Mission](http://ia3.ahoyworld.co.uk/) + * [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee) + * [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/) + * [Cumulus TV: Android TV app that turns any stream/page into a Live Channel](http://cumulustv.herokuapp.com) Do you use Daux.io? Send me a pull request or open an [issue](https://github.com/justinwalsh/daux.io/issues) and I will add you to the list. -## Download +## Install -Download this repository as a zip, and unpack. Copy the files to a web server that can run PHP 5.4 or greater. You can also run the documentation locally using Grunt.js, which is covered at the end of this readme. +``` +composer global require justinwalsh/daux.io +``` + +You can then use the `daux` command line to generate your documentation. + +If the command isn't found, ensure your `$PATH` contains `~/.composer/vendor/bin` + +## Run on a server + +Download this repository as a zip, unpack, and put your documentation in the `docs` folder, you can then serve it with Apache or Nginx. + +## `daux` + +The command line tool has two commands: `generate` and `serve`, running Daux.io without an argument will automatically run the `generate` command. + +You can run `daux --help` to get more details about each command. ## Folders @@ -60,7 +75,7 @@ If you'd prefer to keep your docs somewhere else (like outside of the daux.io ro ## Files -The generator will look for Markdown files (`*.md` and `*.markdown`) inside the `docs` folder and any of the subfolders within `docs`. Additional extensions can be added by editing `global.json` +The generator will look for Markdown files (`*.md` and `*.markdown`) inside the `docs` folder and any of the subfolders within `docs`. You must use underscores instead of spaces. Here are some example file names and what they will be converted to: @@ -99,7 +114,8 @@ If you are interested in having a landing page for a subsection of your docs, al ## Configuration -To customize the look and feel of your documentation, you can create a `config.json` file in the of the `/docs` folder. The `config.json` file is a simple JSON object that you can use to change some of the basic settings of the documentation. +To customize the look and feel of your documentation, you can create a `config.json` file in the of the `/docs` folder. +The `config.json` file is a simple JSON object that you can use to change some of the basic settings of the documentation. ###Title: Change the title bar in the docs @@ -254,9 +270,9 @@ This feature will insruct the router to seek the first available file to use whe ```json { - "live": [ + "live": { "inherit_index": true - ] + } } ``` @@ -306,7 +322,7 @@ The Grunt.js task uses the built in web server in PHP 5.4 to host the docs on yo * Node.js * npm * Grunt.js -* PHP 5.4 or greater (This is because of the built-in web server packaged in 5.4) +* PHP 5.5 or greater This project contains a package.json file, so once you have the requirements installed, you can simply run a `npm install` and then `grunt` in the projects folder to start the local web server. By default the server will run at: http://localhost:8085 @@ -317,7 +333,7 @@ These can be uploaded to a static site hosting service such as pages.github.com Generating a complete set of pages, with navigation ```bash -php generate.php [global.json Relative Location] [Output Directory Relative Direction] +daux --source=docs --destination=static ``` ## Running on IIS @@ -352,23 +368,9 @@ The `web.config` needs an entry for `` under ``: To use clean URLs on IIS 6, you will need to use a custom URL rewrite module, such as [URL Rewriter](http://urlrewriter.net/). -### Less Mime Type - -The `web.config` needs a new `` entry, under `` in ``: - -```xml - - - -``` - -You will only need the mime map entry if you are using a custom theme and receive 404s for `.less` files. - -If you have a global mime map entry for `.less` files set for the server, you will receive an internal server (500) error for having duplicate mime map entries. - ## Compatibility -Daux.io is compatible with php 5.5 and up. +Daux.io is compatible with PHP 5.5 and up. The reason is because some dependencies we have (mainly Symfony and Guzzle) do not support php 5.4 anymore diff --git a/docs/00_Getting_Started.md b/docs/00_Getting_Started.md index 6fb41be..f94d504 100644 --- a/docs/00_Getting_Started.md +++ b/docs/00_Getting_Started.md @@ -47,14 +47,15 @@ Do you use Daux.io? Send us a pull request or open an [issue](https://github.com ## Getting Started -### Download +### Install -Download this repository as a zip, and unpack. Copy the files to a web server that can run PHP 5.3 or greater. -You can also run the documentation locally using Grunt.js, which is covered at the end of this readme. +``` +composer global require justinwalsh/daux.io +``` -If you don't intend to modify Daux.io and just want to use it, you only need to copy `resources`, `daux.phar`, `global.json`, `generate`, `serve` and `index.php` With these, you're ready to create your documentation. +You can then use the `daux` command line to generate your documentation. -If however you wish to do some advanced modifications, I recommend you use the raw version and run `composer install` to get started. +If the command isn't found, ensure your `$PATH` contains `~/.composer/vendor/bin` ### Writing pages @@ -109,11 +110,7 @@ Daux.io is extendable and comes by default with three export formats: [See a detailed feature comparison matrix](01_Features/Multiple_Output_Formats.md) -Here's how you run an export: - -```bash -./generate -``` +To export, run the `daux` command and your documentation will be generated in `static` (you can change the destination with the `--destination` option) [See here for all options](01_Features/Static_Site_Generation.md) diff --git a/docs/01_Features/Live_mode.md b/docs/01_Features/Live_mode.md index 493dc15..733d440 100644 --- a/docs/01_Features/Live_mode.md +++ b/docs/01_Features/Live_mode.md @@ -6,9 +6,9 @@ The whole directory must be scanned on each request. This might not make a big i There are several ways to run the docs locally. You can use something like MAMP or WAMP. -The easiest is to use PHP 5.4's built-in server. +The easiest is to use PHP's built-in server. -For that i've included a short command, run `./serve` in the projects folder to start the local web server. By default the server will run at: http://localhost:8085 +For that i've included a short command, run `daux serve` in the projects folder to start the local web server. By default the server will run at: http://localhost:8085 ## Running Remotely @@ -28,7 +28,7 @@ To enable the same, set the toggle in the `config.json` file in the `/docs` fold ### Apache -Copy the files from the repo to a web server that can run PHP 5.3 or greater. +Copy the files from the repo to a web server that can run PHP 5.5 or greater. There is an included `.htaccess` for Apache web server. diff --git a/docs/01_Features/Static_Site_Generation.md b/docs/01_Features/Static_Site_Generation.md index 72157ab..dc1e3e4 100644 --- a/docs/01_Features/Static_Site_Generation.md +++ b/docs/01_Features/Static_Site_Generation.md @@ -8,7 +8,7 @@ If you don't want to serve the live version of your site, you can also generate Generating a complete set of pages, with navigation ```bash -./generate --destination=[Output Directory Relative Direction] +daux --destination=[Output Directory Relative Direction] ``` ## Options @@ -16,7 +16,7 @@ Generating a complete set of pages, with navigation For more options, run ```bash -./generate --help +daux generate --help ``` ### Specify the configuration file @@ -27,7 +27,7 @@ Valid options are `html`, `confluence` or `html-file`. You can also add your own formats through Processors ```bash -./generate --format=html +daux --format=html ``` ### Specify a processor @@ -37,7 +37,7 @@ A processor can be specified through the `--processor` option, this should be t By running : ```bash -./generate --processor=Processor +daux --processor=Processor ``` Daux will be looking for `Todaymade\Daux\Extension\Processor` inside the `daux` folder. @@ -49,7 +49,7 @@ You can try to run this command, we added a small example Processor. By default, the source is taken from the `docs_directory` configuration value in `global.json` but you can override it here. ```bash -./generate --source=docs_to_generate +daux --source=docs_to_generate ``` The path can be absolute or relative @@ -59,7 +59,7 @@ The path can be absolute or relative By default the destination is `static` ```bash -./generate --destination=generated_docs +daux --destination=generated_docs ``` The path can be absolute or relative diff --git a/docs/10_For_Developers/Creating_a_Processor.md b/docs/10_For_Developers/Creating_a_Processor.md index 409bb16..acb92f7 100644 --- a/docs/10_For_Developers/Creating_a_Processor.md +++ b/docs/10_For_Developers/Creating_a_Processor.md @@ -28,7 +28,7 @@ also, add this at the beginning of the file: use Todaymade\Daux\Tree\Root; ``` -Let's just try if it works by running `./generate --processor=Processor` +Let's just try if it works by running `daux --processor=Processor` Yes, you get a big array dump! You're good to go. diff --git a/libs/Format/Confluence/Api.php b/libs/Format/Confluence/Api.php index 7b2747d..eb7f2e1 100644 --- a/libs/Format/Confluence/Api.php +++ b/libs/Format/Confluence/Api.php @@ -2,7 +2,6 @@ use GuzzleHttp\Client; use GuzzleHttp\Exception\BadResponseException; -use GuzzleHttp\Exception\RequestException; class Api { @@ -43,7 +42,7 @@ class Api * this will give little bit more sense to it and return it * * @param BadResponseException $e - * @return RequestException + * @return \Exception */ protected function handleError(BadResponseException $e) { diff --git a/libs/Format/Confluence/DuplicateTitleException.php b/libs/Format/Confluence/DuplicateTitleException.php index a6f4875..3b4f6b7 100644 --- a/libs/Format/Confluence/DuplicateTitleException.php +++ b/libs/Format/Confluence/DuplicateTitleException.php @@ -1,5 +1,5 @@