Merge pull request #1 from RealOrangeOne/documentation

Documentation

README.md

@@ -16,6 +16,9 @@ Convert markdown files into PDF Documents.
 __Note__: All features are completely optional
 
 
+### Documentation
+Documentation can be found in the `docs/` directory.
+
 ### Usage
     $ mdp --help
     usage: mdp [-h] [-v] [--update-csl]

docs/installation.md

@@ -0,0 +1,34 @@
+# Installation
+
+### Installing dependencies
+These applications will not be installed with `md-pdf`, so need to be installed through your OS's package manager.
+- `pandoc`
+- `pandoc-citeproc`
+- `wkhtmltopdf` (With QT - [See Here](https://pypi.python.org/pypi/pdfkit))
+
+
+#### Arch Linux
+    yaourt -S pandoc pandoc-citeproc wkhtmltopdf-static
+    
+#### Ubuntu
+    sudo apt install pandoc pandoc-citeproc
+
+To install the correct version of `wkhtmltopdf`, you will need to build it yourself using [this script](https://github.com/JazzCore/python-pdfkit/blob/master/travis/before-script.sh).
+
+#### Windows
+__Note__: Windows is an untested platform, these installation instructions are only theoretical!
+
+Pandoc (and `pandoc-citeproc`) can be installed using the installer found [here](https://github.com/jgm/pandoc/releases/).
+
+`wkhtmltopdf` can be installed from the [official website](https://wkhtmltopdf.org/downloads.html).
+
+
+### Installing `md-pdf`.
+This application isn't available through Pypi directly, but can still be installed using pip.
+    
+    pip install https://github.com/RealOrangeOne/md-pdf
+    
+This should install the rest of the dependencies. To check it installed correctly, you can run this:
+    
+    mdp --help
+If you see the help information, it's installed correctly. If not, please submit an [issue](https://github.com/RealOrangeOne/md-pdf).

docs/markdown.md

@@ -0,0 +1,14 @@
+# Markdown
+
+Whilst `md-pdf` theoretically supports all formats pandoc does, it's only been tested and and validated to support markdown.
+ 
+Information about markdown as a format can be found [here](http://daringfireball.net/projects/markdown/). The standard format and syntax is used, however there are some additional features to improve the output format.
+
+### Images
+Images take the same syntax as with standard markdown: 
+   
+    ![title](url)
+
+Referencing files inside your project directory can be done with a path relative to the project directory. You can use images direct from online, however you'll need to be connected to the internet when generating.
+
+The title for the image is also used as the caption, and is displayed directly under the images.

docs/output.md

@@ -0,0 +1,9 @@
+# Output
+
+Rather than outputting a single file, `md-pdf` outputs to a directory, allowing multiple different output formats.
+
+### Supported formats
+- HTML
+- PDF
+
+The output files will be named `output` with their formats default extension (eg `output.html`)

docs/referencing.md

@@ -0,0 +1,33 @@
+# Referencing
+
+Referencing is powered by `pandoc-citeproc`, so any format supported by it is supported. A list of supported formats can be found [here](https://github.com/jgm/pandoc-citeproc/blob/master/man/pandoc-citeproc.1.md).
+
+__Remember__: To use YAML, your file must end `.yaml` rather than `.yml`!
+
+## CSL Files
+There are many different ways of referencing, both inline, and in a bibliography. `md-pdf` supports _all_ of them.
+
+The configuration used for this is stored in `csl` files, which can be downloaded through `md-pdf`. See the usage instructions on how to download these.
+
+There's a full list of available `csl` files [here](https://github.com/citation-style-language/styles/).
+
+## Example
+Assuming youre using the same bibliography as the example, an input of:
+
+```markdown
+@item1 says blah.
+```
+Will render as:
+```
+Doe (2005) says blah.
+```
+
+### Advanced Citation
+You can also use more advanced referencing to be more specific:
+```markdown
+A citation group [see @item1 p. 34-35; also @item3 chap. 3].
+```
+will result in:
+```
+A citation group (see Doe 2005, 34–35; also Doe and Roe 2007, chap. 3)
+```

docs/usage.md

@@ -0,0 +1,25 @@
+# Usage
+    $ mdp --help
+    usage: mdp [-h] [-v] [--update-csl]
+    
+    optional arguments:
+      -h, --help     show this help message and exit
+      -v, --verbose  Set verbosity level (repeat argument)
+      --update-csl   Update CSL files
+
+## Running the application
+Assuming you're in a directory with a valid `mdp.yml` file, simply run `mdp` to build your files to the output directory!
+
+## Downloading CSL Files
+In order to use referencing properly, `csl` files need to be downloaded. These tell `md-pdf` what style of referencing you're using, and how to output the bibliography.
+
+To download these, simply run:
+
+    mdp --update-csl
+
+This will download the `csl` files into the install directory of the application. It only needs to be run once, however can be run whenever to update the definitions from [here](https://github.com/citation-style-language/styles/).
+
+## Verbosity
+By default, when building, the application doesn't output anything to the console. It simply runs, and terminates when it's finished. Obviously errors are still reported.
+
+To increase the verbosity level, simply add the `-v` argument when running the application. This can be chained a maximum of 3 times (`-vvv`), subsequent repetition will be ignored.

test-files/1intro.md

@@ -0,0 +1,5 @@
+# Test content
+
+_Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ante purus, scelerisque sed pulvinar eget, suscipit feugiat augue. Cras quis quam ac dui aliquam rhoncus eu id diam. Cras dapibus vel nunc in finibus. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Nulla a lacinia nibh. Aenean finibus mauris et est euismod aliquam. Curabitur dictum nulla quis turpis fringilla vestibulum at eget ligula. Donec et ultricies massa, ut volutpat neque. Praesent elementum ultrices urna at finibus. Nunc risus mi, porta sed eros sit amet, sagittis sollicitudin velit. Nulla a felis in tellus gravida pretium sit amet eget libero. Donec aliquet ac est semper molestie._
+
+__Curabitur arcu velit, faucibus sed condimentum vitae, consectetur a lectus. Fusce a cursus magna. Nam vel posuere erat, in congue purus. Aliquam aliquet eu leo vel cursus. Vestibulum mattis est ac diam finibus, in aliquet erat iaculis. Phasellus est quam, rutrum a tempus non, vehicula vitae tellus. Nam nec leo consectetur, aliquam lorem eget, dignissim arcu. Phasellus vitae convallis urna, ac aliquet purus. Vivamus nisl mauris, volutpat quis pretium non, fringilla non dui. Pellentesque velit justo, pretium a porta nec, varius ac lacus.__ 

test-files/2-pandoc.md

@@ -0,0 +1,23 @@
+
+
+-   [@nonexistent]
+
+-   @nonexistent
+
+-   @item1 says blah.
+
+-   @item1 [p. 30] says blah.
+
+-   @item1 [p. 30, with suffix] says blah.
+
+-   @item1 [-@item2 p. 30; see also @item3] says blah.
+
+-   A citation group [see @item1 p. 34-35; also @item3 chap. 3].
+
+-   Another one [see @item1 p. 34-35].
+
+-   Citation with a suffix and locator [@item1 pp. 33, 35-37, and nowhere else].
+
+-   Citation with suffix only [@item1 and nowhere else].
+
+-   With some markup [*see* @item1 p. **32**].

test-files/3-image.md

@@ -1,4 +1,4 @@
-# Test content
+# Test Image
 
 
 ![title](./test-image.png)

test-files/bib.yaml

@@ -0,0 +1,42 @@
+---
+references:
+- id: item1
+  type: book
+  author:
+  - family: Doe
+    given: John
+  issued:
+  - year: '2005'
+  title: First book
+  publisher: Cambridge University Press
+  publisher-place: Cambridge
+
+- id: item2
+  type: article-journal
+  author:
+  - family: Doe
+    given: John
+  issued:
+  - year: '2006'
+  title: Article
+  container-title: Journal of Generic Studies
+  page: '33-34'
+  volume: '6'
+
+- id: item3
+  type: chapter
+  author:
+  - family: Doe
+    given: John
+  - family: Roe
+    given: Jenny
+  editor:
+  - family: Smith
+    given: Sam
+  issued:
+  - year: '2007'
+  title: Why water is wet
+  container-title: Third book
+  publisher: Oxford University Press
+  publisher-place: Oxford
+...

test-files/end.md

@@ -0,0 +1,3 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus accumsan justo nisi, eget eleifend eros blandit sit amet. Mauris ligula neque, posuere a fringilla quis, pharetra ac nisi. Duis lacus dui, sodales sit amet semper sit amet, euismod ut erat. Donec faucibus, nisi eget condimentum rutrum, tellus orci rhoncus ante, sed laoreet odio ex eu mi. In sem neque, ultrices et laoreet at, vestibulum non justo. Vestibulum tempus pulvinar vulputate. Vestibulum tellus nunc, pellentesque eget dolor eu, porta molestie nunc. Pellentesque at feugiat nisl. Aenean bibendum, lorem ut vehicula laoreet, ante eros sollicitudin augue, vitae volutpat diam augue a purus. Sed fermentum et enim quis elementum. Proin commodo, erat a egestas ultrices, ipsum tellus finibus neque, non aliquam nulla urna non magna. Nulla facilisi. Vivamus in lacinia neque. Aenean gravida elit ipsum, ac rutrum ligula vehicula a.
+
+Ut imperdiet sit amet sem egestas iaculis. Aliquam sit amet posuere ante, eget iaculis turpis. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Phasellus maximus lacinia malesuada. Nullam ullamcorper rhoncus massa, a eleifend enim malesuada ullamcorper. Sed sed consequat nibh. Vestibulum fringilla dignissim nulla, nec viverra felis elementum et. Cras tristique posuere luctus. Mauris dapibus pellentesque volutpat. In porttitor placerat felis, non ultrices mi elementum eget. Aenean id lectus egestas, imperdiet dolor ut, varius ante. Mauris vulputate congue lectus, vel tempus nisl volutpat et. Duis dapibus mauris vel aliquet porttitor. Mauris nec risus tempus, pharetra lectus sit amet, molestie ex. Vivamus dapibus mi quis porttitor fermentum. Maecenas imperdiet metus at mi varius pretium. 

test-files/mdp.yml

@@ -5,7 +5,7 @@ output_formats:
 output_dir: out/
 bibliography:
   references: bib.yaml
-  csl: apa
+  csl: chicago-author-date
 context:
   foo: bar
   bar: foo