62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
|
# DL4J auto-generated documentation
|
||
|
|
|
||
|
|
## Building
|
||
|
|
|
||
|
|
Run `./gen_all_docs.sh` to generate documentation from source for all supported projects. For each documentation module, files will be put into a `doc_sources` folder where they are staged for copying to the primary docs repository. Note that the autogen docs require Python 2.
|
||
|
|
|
||
|
|
To deploy a new version of documentation, first make sure to set `$DL4J_DOCS_DIR` to your local copy of
|
||
|
|
https://github.com/deeplearning4j/deeplearning4j-docs and set `$DL4J_VERSION` to a URI-friendly version string such as `v100-RC` (note the lack of decimals). Then run `./copy-to-dl4j-docs.sh`. This puts documentation
|
||
|
|
into the right folders and you can use `git` to create a PR and update the live docs.
|
||
|
|
|
||
|
|
The structure of this project (template files, generating code, mkdocs YAML) is closely aligned
|
||
|
|
with the [Keras documentation](keras.io) and heavily inspired by the [Keras docs repository](https://github.com/keras-team/keras/tree/master/docs).
|
||
|
|
|
||
|
|
## File structure
|
||
|
|
|
||
|
|
Each major module or library in Eclipse Deeplearning4j has its own folder. Inside that folder are three essential files:
|
||
|
|
|
||
|
|
- `templates/`
|
||
|
|
- `pages.json`
|
||
|
|
- `README.md`
|
||
|
|
|
||
|
|
Note that the folder names don't exactly match up with the modules in the `pom.xml` definitions across DL4J. This is because some of the documentation is consolidated (such as DataVec) or omitted due to its experimental status or because it is low-level in the code.
|
||
|
|
|
||
|
|
Templates must maintain a flat file structure. This is to accommodate Jekyll collections when the docs are published. Don't worry about having similarly named files in different doc modules - the module name is prepended when the docs are generated.
|
||
|
|
|
||
|
|
## Creating templates
|
||
|
|
|
||
|
|
Each template has a Jekyll header at the top:
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
---
|
||
|
|
title: Deeplearning4j Autoencoders
|
||
|
|
short_title: Autoencoders
|
||
|
|
description: Supported autoencoder configurations.
|
||
|
|
category: Models
|
||
|
|
weight: 3
|
||
|
|
---
|
||
|
|
```
|
||
|
|
|
||
|
|
All of these definitions are necessary.
|
||
|
|
|
||
|
|
- `title` is the HTML title that appears for a Google result or at the top of the browser window.
|
||
|
|
- `short_title` is a short name for simple navigation in the user guide.
|
||
|
|
- `description` is the text that appears below the title in a search engine result.
|
||
|
|
- `category` is the high-level category in the user guide.
|
||
|
|
- `weight` is the ordering that the doc will appear in navigation, the larger the lower the listing.
|
||
|
|
|
||
|
|
## Creating links
|
||
|
|
|
||
|
|
**All links to other docs need to be relative.** This prolongs the life of the documentation and reduces maintenance. The basic structure of a link to another doc looks like:
|
||
|
|
|
||
|
|
```
|
||
|
|
<module name>-<file name>
|
||
|
|
```
|
||
|
|
|
||
|
|
So if you created a DataVec doc with the name `iterators.md` in the `datavec` module, your relative link will look like:
|
||
|
|
|
||
|
|
```
|
||
|
|
./datavec-iterators
|
||
|
|
```
|
||
|
|
|
||
|
|
Note the omission of the file extension `.md`. Jekyll automatically generates a clean URL for us to use.
|