gendoc 0.0.4

Document generator using Ddoc D language standard feature for dub package.


To use this package, run the following command in your project's root directory:


This package provides sub packages which can be used individually:

gendoc:candydoc - Document generator using Ddoc D language standard feature for dub package.

gendoc

GitHub tag CI Status codecov

gendoc is a tool for generating documents using the built-in document generation feature of D language compilers.

This is forked from dxml/gendocs.d, and file search and specification of compilation options based on dub package information are added.

Sample Pages

  • Default style: http://shoo.github.io/gendoc
  • Candydoc: http://shoo.github.io/gendoc/candydoc

How to build

dub build

How to use

To use gendoc, move current directory to the dub project and enter the following command:

gendoc

Or, can be run using dub package manager:

dub run gendoc

You can apply CanDyDoc style:

dub run gendoc:candydoc

In addition, to import template document styles using gendoc's dub package:

dub build gendoc -c=init

CanDyDoc:

dub build gendoc:candydoc -c=init

When you want to know the detail of usage, you can use the help command to display help messages:

gendoc -h
.OptionsTypeDesctiptionDefault
-a--archstringArchtecture of dub project.x86_64
-b--buildstringBuild type of dub project.debug
-c--configstringConfiguration of dub project.
--compilerstringSpecifies the compiler binary to use (can be a path).dmd
--gendocDdocsstring[]Ddoc sources of document files.["ddoc"] if exists
--gendocSourceDocsstring[]Source of document files.["source_docs"] if exists
--gendocTargetstringTarget directory of generated documents.docs
--gendocConfigstringConfiguration file of gendoc."gendoc.json" if exists
--rootstringPath to operate in instead of the current working dir..
--singleFileboolSingle file generation mode.false
-v--varboseboolDisplay varbose messages.false
-q--quietboolNon-display messages.false
-h--helpboolThis help information.false

Settings

You can change the settings of the directory where the *.ddoc, *.dd, *.html etc. source files are placed according to your preference. The directory is searched using the following procedure:

Search settings in the following order(Top item in list has highest priority):

  1. Command line argument specifiered
    1. (--gendocConfig=<jsonfile>)
    2. (--gendocConfig=<directory>)/settings.json
    3. (--gendocConfig=<directory>)/gendoc.json
    4. (--gendocConfig=<directory>)/ddoc and (--gendocConfig=<directory>)/docs
    5. (--gendocConfig=<directory>)/ddoc and (--gendocConfig=<directory>)/source_docs
  2. Search current directory
    1. ./.gendoc.json
    2. ./gendoc.json
    3. ./.gendoc/settings.json
    4. ./.gendoc/gendoc.json
    5. ./.gendoc/ddoc and ./.gendoc/docs
    6. ./.gendoc/ddoc and ./.gendoc/source_docs
    7. ./ddoc and ./source_docs * (docs may be a target)
  3. Search $(HOME) (POSIX) or %USERPROFILE (Windows) directory
    1. $(HOME)/.gendoc.json
    2. $(HOME)/gendoc.json
    3. $(HOME)/.gendoc/settings.json
    4. $(HOME)/.gendoc/gendoc.json
    5. $(HOME)/.gendoc/ddoc and $(HOME)/.gendoc/docs
    6. $(HOME)/.gendoc/ddoc and $(HOME)/.gendoc/source_docs
  4. Search (gendocExeDir) directory
    1. (gendocExeDir)/.gendoc.json
    2. (gendocExeDir)/gendoc.json
    3. (gendocExeDir)/.gendoc/settings.json
    4. (gendocExeDir)/.gendoc/gendoc.json
    5. (gendocExeDir)/.gendoc/ddoc and (gendocExeDir)/.gendoc/docs
    6. (gendocExeDir)/.gendoc/ddoc and (gendocExeDir)/.gendoc/source_docs
    7. (gendocExeDir)/ddoc and (gendocExeDir)/source_docs * (docs may be a gendoc's document target)
  5. Search (gendocExeDir)/../etc directory
    1. (gendocExeDir)/../etc/.gendoc.json
    2. (gendocExeDir)/../etc/gendoc.json
    3. (gendocExeDir)/../etc/.gendoc/settings.json
    4. (gendocExeDir)/../etc/.gendoc/gendoc.json
    5. (gendocExeDir)/../etc/.gendoc/ddoc and (gendocExeDir)/../etc/.gendoc/docs
    6. (gendocExeDir)/../etc/.gendoc/ddoc and (gendocExeDir)/../etc/.gendoc/source_docs

gendoc.json / .gendoc/settings.json

You can change the gendoc settings by adding gendoc.json or .gendoc/settings.json to the dub package.

Example:

{
    "//": "Same to --gendocDdocs option. (Run-time arguments are preferred.)",
    "//": "Specify a directory path where the relative path from the root of dub package.",
    "//": "The directory where the `*.ddoc` files to be specified in the compilation",
    "//": "argument when generating HTML are stored.",
    "ddocs": [ "ddocs" ],
    
    "//": "Same to --gendocSourceDocs option. (Run-time arguments are preferred.)",
    "//": "Specify a directories path where the relative path from the root of dub package.",
    "//": "`*.dd` files are compiled and other files are simply copied.",
    "sourceDocs": [ "source_docs" ],
    
    "//": "Same to --gendocTarget option. (Run-time arguments are preferred.)",
    "//": "Specify a directory path where the relative path from the root of dub package.",
    "//": "The resulting HTML is generated in this directory.",
    "ddocs": "docs",
    
    "//": "Specify names there exactly match the path.",
    "//": "For the path, specify the relative path from the first one of the",
    "//": "importPaths of dub settings.",
    "//": "Matched files are excluded from document generation.",
    "excludePaths": ["src/_internal", "src/ut.d"],
    
    "//": "Specify regex patterns there match the path.",
    "//": "For the path, specify the relative path from the first one of the",
    "//": "importPaths of dub settings.",
    "//": "Matched files are excluded from document generation.",
    "excludePatterns": [
        "(?:(?<=/)|^)\\.[^/.]+$",
        "(?:(?<=[^/]+/)|^)_[^/]+$",
        "(?:(?<=[^/]+/)|^)internal(?:\\.d)?$"
    ],
    
    "//": "Specify a name that exactly matches the full dub package name.",
    "//": "Matched packages are excluded from document generation.",
    "excludePackages": ["gendoc:example", "gendoc:test"],
    
    "//": "Specify regex patterns there match the full dub package name.",
    "//": "Matched packages are excluded from document generation.",
    "excludePackagePatterns": [
        "(?:(?<=[^:]+/)|^)_[^/]+$",
        ":docs?$"
    ]
}

mustache

You can use mustache as a way to embed information that is difficult to manage manually, such as a list of modules, in a ddoc file. Save it with the extension *.ddoc.mustache, *.dd.mustache, such as module_list.ddoc.mustache.

MODULE_MENU={{# dub_pkg_info }}
$(MENU_DUBPKG {{ name }}, {{ version }},
	{{# children }}{
		"file": "_module_info",
		"map": {
			"tag_pkg":"MENU_PKG",
			"tag_mod":"MENU_MOD"
		}
	}{{/ children }}
)
{{/ dub_pkg_info }}

Available tags are as below:

LocationTag nameTypeDescription
1. (root of package)nameVariablesDub package name.
2. (root of package)versionVariablesDub package version.
3. (root of package)dirVariablesPath of dub package directory.
4. (root of package)commandLambdasExecute command and store result.
5. (root of package)rdmdLambdasExecute dlang code with rdmd --eval and store the result to standard output.
6. (root of package)environemntLambdasExpand and store environment variables.
7. (root of package)childrenLambdasThe package and module information included in the dub package is embedded.
7.1. childrenis_packageSectionSection used when the current element is a package.
7.1.1. is_packagehaspackagedSectionSection used when the current package has a package.d
7.1.1.1. haspackagednameVariablesName of package. (foo/bar/package.d -> bar)
7.1.1.2. haspackagedpage_urlVariablesUrl of the document of package.d
7.1.1.3. haspackageddubpackagenameVariablesName of dub package.
7.1.1.3. haspackagedpackage_nameVariablesName of package. (foo/bar/package.d -> foo.bar)
7.1.1.4. haspackagedmodule_nameVariablesName of module. (foo/bar/package.d -> (none))
7.1.1.5. haspackagedfullmodulenameVariablesFullname of module. (foo/bar/package.d -> foo.bar)
7.1.1.6. haspackagedcommandLambdasExecute command and store result.
7.1.1.7. haspackagedrdmdLambdasExecute dlang code with rdmd --eval and store the result to standard output.
7.1.1.8. haspackagedenvironemntLambdasExpand and store environment variables.
7.1.1.9. haspackagedchildrenLambdasThe package and module information included in the package is embedded.
7.1.2. is_packagenopackagedSectionSection used when the current package has not a package.d
7.1.2.1. nopackagednameVariablesName of package(only bottom name). (foo/bar -> bar)
7.1.2.2. nopackageddubpackagenameVariablesName of dub package.
7.1.2.3. nopackagedpackage_nameVariablesName of package. (foo/bar -> foo.bar)
7.1.1.4. nopackagedcommandLambdasExecute command and store result.
7.1.1.5. nopackagedrdmdLambdasExecute dlang code with rdmd --eval and store the result to standard output.
7.1.1.6. nopackagedenvironemntLambdasExpand and store environment variables.
7.1.2.7. nopackagedchildrenLambdasThe package and module information included in the package is embedded.
7.2. childrenis_moduleSectionSection used when the current element is a module.
7.2.1. is_modulenameVariablesName of package. (foo/bar/hoge.d -> hoge)
7.2.2. is_modulepage_urlVariablesUrl of the document of module.
7.2.3. is_modulepackage_nameVariablesName of package. (foo/bar/hoge.d -> foo.bar)
7.2.4. is_moduledubpackagenameVariablesName of dub package.
7.2.5. is_modulemodule_nameVariablesName of module. (foo/bar/hoge.d -> hoge)
7.2.6. is_modulefullmodulenameVariablesFullname of module. (foo/bar/package.d -> foo.bar.hoge)
7.2.7. is_modulecommandLambdasExecute command and store result.
7.2.8. is_modulerdmdLambdasExecute dlang code with rdmd --eval and store the result to standard output.
7.2.9. is_moduleenvironemntLambdasExpand and store environment variables.

As it appears above, {{# children }} {{/ children }} is special. Recursive embedding is done to represent the package tree structure. At that time, it is possible to change the contents with the information described inside. The information is in JSON format or mustache format.

  • If the literal start token of {, [, " is included in the same line with {{# children }} start tag, it is treated as JSON format.
  • In the case of JSON format, it is possible to take one of three types: string, array, or object.
    • string: treat the string as "mustache".
    • array: Interpret as command line.
    OptionsTypeDescription
    (first argumenet)stringfile name or path of mustache
    -i / --importstring[]search path of mustache file (first argument)
    -m / --mapstring[stirng]define additional variable
    -u / --usestring[]usable section
    • object: Interpret the data structure.

    FieldTypeDescription
    filestringfile name or path of mustache
    importsstring[stirng]search path of mustache file (file field)
    contentsstringmustache (File field takes precedence)
    mapstring[stirng]define additional variable
    useSectionsstring[]usable section
  • If the file is specified above, rendering will be performed with the target file.
  • If none of the above, JSON parsing fails, or a muctache string is specified even in JSON format, treat it as a mustache string.
  • If a mustache-style string is specified in either way, the string is rendered directly as mustache instead of a file.

License

gendoc is licensed by Boost Software License 1.0

gendoc depends on:

Generated html by dendoc depends on:

Authors:
  • SHOO
Sub packages:
gendoc:candydoc
Dependencies:
dub, mustache-d
Versions:
0.0.4 2019-Oct-22
0.0.3 2019-Aug-26
0.0.2 2019-Aug-17
0.0.1 2019-Aug-17
~master 2019-Oct-22
Show all 5 versions
Download Stats:
  • 0 downloads today

  • 0 downloads this week

  • 1 downloads this month

  • 73 downloads total

Score:
0.0
Short URL:
gendoc.dub.pm