Document the new command line tool
This commit is contained in:
Stéphane Goetz
bovenliggende
08a5fc3f56
commit
2081acc3c5
70
README.md
70
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: <a href="http://localhost:8085" target="_blank">http://localhost:8085</a>
|
||||
|
||||
@ -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 `<rewrite>` under `<system.webServer>`:
|
||||
|
||||
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 `<mimeMap>` entry, under `<staticContent>` in `<system.webServer>`:
|
||||
|
||||
```xml
|
||||
<staticContent>
|
||||
<mimeMap fileExtension=".less" mimeType="text/css" />
|
||||
</staticContent>
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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 <a href="http://www.mamp.info/en/index.html" target="_blank">MAMP</a> or <a href="http://www.wampserver.com/en/" target="_blank">WAMP</a>.
|
||||
|
||||
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: <a href="http://localhost:8085" target="_blank">http://localhost:8085</a>
|
||||
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: <a href="http://localhost:8085" target="_blank">http://localhost:8085</a>
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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)
|
||||
{
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<?php namespace Todaymade\Daux\Format\Confluence;
|
||||
|
||||
class DuplicateTitleException extends \GuzzleHttp\Exception\RequestException
|
||||
class DuplicateTitleException extends \RuntimeException
|
||||
{
|
||||
}
|
||||
|
||||
Laden…
Verwijs in nieuw issue
Block a user