daux.io/docs/00_Getting_Started.md

159 regels
5.1 KiB
Markdown

2013-06-12 00:28:29 +02:00
**Daux.io** is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.
2013-06-03 15:32:55 +02:00
2016-04-12 08:38:52 +02:00
[TOC]
2013-06-04 19:26:14 +02:00
## Features
2013-06-03 15:32:55 +02:00
2015-12-12 00:22:43 +01:00
### For Authors
* [Auto Generated Navigation / Page sorting](01_Features/Navigation_and_Sorting.md)
* [Internal documentation links](01_Features/Internal_links.md)
* [CommonMark compliant](01_Features/CommonMark_compliant.md)
* [Auto created homepage/landing page](01_Features/Landing_page.md)
* [Multiple Output Formats](01_Features/Multiple_Output_Formats.md)
* [Multiple Languages Support](01_Features/Multilanguage.md)
* [No Build Step](01_Features/Live_mode.md)
* [Static Output Generation](01_Features/Static_Site_Generation.md)
* [Table of Contents](01_Features/Table_of_contents.md)
2015-12-12 00:22:43 +01:00
### For Developers
* [Auto Syntax Highlighting](01_Features/Auto_Syntax_Highlight.md)
* [Extend Daux.io with Processors](01_For_Developers/Creating_a_Processor.md)
2015-12-12 00:22:43 +01:00
* Full access to the internal API to create new pages programatically
* Work with pages metadata
### For Marketing
* 100% Mobile Responsive
2013-06-12 00:28:29 +02:00
* 4 Built-In Themes or roll your own
* Functional, Flat Design Style
2015-12-12 00:22:43 +01:00
* Optional code float layout
2013-06-04 19:26:14 +02:00
* Shareable/Linkable SEO Friendly URLs
2013-07-22 17:38:04 +02:00
* Supports Google Analytics and Piwik Analytics
2013-06-04 19:26:14 +02:00
2013-06-04 20:23:01 +02:00
## Demos
2013-06-12 00:28:29 +02:00
This is a list of sites using Daux.io:
2013-06-04 20:23:01 +02:00
2013-06-21 18:36:57 +02:00
* [Daux.io](http://daux.io)
* [jDrupal](http://jdrupal.easystreet3.com/8/docs/)
* [DrupalGap](http://docs.drupalgap.org/8/)
* [Invade & Annex 3 - An Arma 3 Co-operative Mission](http://ia3.ahoyworld.co.uk/)
2013-07-29 03:58:19 +02:00
* [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee)
* [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/)
2013-06-04 20:23:01 +02:00
2017-09-13 21:43:40 +02:00
Do you use Daux.io? Send us a pull request or open an [issue](https://github.com/dauxio/daux.io/issues) and I will add you to the list.
2013-06-04 20:23:01 +02:00
2015-12-12 00:22:43 +01:00
## Getting Started
2016-07-29 23:20:01 +02:00
### Install
2013-06-04 19:26:14 +02:00
2017-09-13 22:47:53 +02:00
#### PHP and Composer
If you have PHP and Composer installed, you can install the dependency
```bash
2017-09-13 21:43:40 +02:00
composer global require dauxio/daux.io
2017-09-13 22:47:53 +02:00
# Next to your `docs` folder, run
daux generate
2016-07-29 23:20:01 +02:00
```
2015-07-21 09:49:49 +02:00
2016-07-29 23:20:01 +02:00
You can then use the `daux` command line to generate your documentation.
2015-07-21 09:49:49 +02:00
2016-07-29 23:20:01 +02:00
If the command isn't found, ensure your `$PATH` contains `~/.composer/vendor/bin`
2013-06-04 19:26:14 +02:00
2017-09-13 22:47:53 +02:00
#### Docker
Or if you wish to use Docker, the start of the command will be :
```bash
docker run --rm -it -w /build -v "$PWD":/build daux/daux.io daux
```
Any parameter valid in the PHP version is valid in the Docker version
2015-12-12 00:22:43 +01:00
### Writing pages
2015-07-19 16:36:59 +02:00
2015-12-12 00:22:43 +01:00
Creating new pages is very easy:
1. Create a markdown file (`*.md` or `*.markdown`)
2. Start writing
2013-06-04 20:23:01 +02:00
2015-12-12 00:22:43 +01:00
By default, the generator will look for folders in the `docs` folder.
Add your folders inside the `docs` folder. This project contains some example folders and files to get you started.
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
You can nest folders any number of levels to get the exact structure you want.
The folder structure will be converted to the nested navigation.
2013-06-04 19:26:14 +02:00
You must use underscores instead of spaces. Here are some example file names and what they will be converted to:
2013-06-04 19:26:14 +02:00
2013-06-04 20:23:01 +02:00
**Good:**
2013-06-04 19:26:14 +02:00
2013-06-04 20:23:01 +02:00
* 01_Getting_Started.md = Getting Started
* API_Calls.md = API Calls
* 200_Something_Else-Cool.md = Something Else-Cool
* _5_Ways_to_Be_Happy.md = 5 Ways To Be Happy
2013-06-04 20:23:01 +02:00
**Bad:**
* File Name With Space.md = FAIL
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
### See your pages
2013-06-12 00:28:29 +02:00
2015-12-12 00:22:43 +01:00
Now you can see your pages. you have two options for that : serve them directly, or generate to various formats.
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
We recommend the first one while you write your documentation, you get a much quicker feedback while writing.
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
#### Serving files
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
You can use PHP's embedded web server by running the following command in the root of your documentation
2013-06-04 19:26:14 +02:00
2013-07-29 03:58:19 +02:00
```
2015-12-12 00:22:43 +01:00
./serve
2013-07-29 03:58:19 +02:00
```
2013-06-21 21:36:50 +02:00
2015-12-12 00:22:43 +01:00
Upload your files to an apache / nginx server and see your documentation
2013-07-22 17:38:04 +02:00
[More informations here](01_Features/Live_mode.md)
2013-10-22 22:50:46 +02:00
2015-12-12 00:22:43 +01:00
#### Export to other formats
2014-05-31 07:43:07 +02:00
2015-12-12 00:22:43 +01:00
Daux.io is extendable and comes by default with three export formats:
2013-07-29 20:58:04 +02:00
2015-12-12 00:22:43 +01:00
- Export to HTML, same as the website, but can be hosted without PHP.
- Export all documentation in a single HTML page
- Upload to your Atlassian Confluence server.
2015-07-19 16:36:59 +02:00
[See a detailed feature comparison matrix](01_Features/Multiple_Output_Formats.md)
2015-07-19 16:36:59 +02:00
2016-07-29 23:20:01 +02:00
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)
2015-12-12 00:22:43 +01:00
## Configuration
Now that you got the basics, you can also [see what you can configure](05_Configuration/_index.md)
2013-07-30 15:56:16 +02:00
## PHP Requirements
2017-06-07 22:49:35 +02:00
Daux.io is compatible with PHP 5.6 and up.
2017-06-07 22:49:35 +02:00
The reason is because some dependencies we have do not support php 5.5 anymore.
### Extensions
PHP Needs the following extension to work : `php-mbstring` and `php-xml`.
If you encounter an error similar to `utf8_decode() not found` this means that you're missing the `php-xml` package. (We've seen it happen only on PHP 7)
2013-07-30 15:56:16 +02:00
## Known Issues
- __Windows UTF-8 files support__ Files with UTF-8 characters cannot be handled on windows with PHP5, PHP7 should work fine.
2013-06-04 20:23:01 +02:00
## Support
2013-06-04 19:26:14 +02:00
2017-09-13 21:43:40 +02:00
If you need help using Daux.io, or have found a bug, please create an issue on the <a href="https://github.com/dauxio/daux.io/issues" target="_blank">GitHub repo</a>.