path: root/build/conf/docs.conf

# tag:docs
TOUCH_DOCS=$YMAKE_PYTHON ${input:"build/scripts/touch.py"} ${kv;hide:"p DC"} ${kv;hide:"pc light-cyan"} $TARGET
TOUCH_DOCS_MF=$TOUCH_DOCS && $GENERATE_MF

# tag:docs
_DOCS_USE_PLANTUML=no
_DOCS_EXTRA_TOOLS=
_DOCS_EXTRA_INPUTS=
_DOCS_ENV=
_DOCS_KV=${kv;hide:"p DO"} ${kv;hide:"pc light-cyan"} ${kv;hide:"show_out yes"}

_DOCS_PLANTUML_ENV=\
${env:"JAVA_PATH=$JDK_RESOURCE_GLOBAL/bin/java"} \
${env:"PLANTUML_PATH=${ARCADIA_BUILD_ROOT}/contrib/tools/plantuml/plantuml.run.cp.jar"} \
${env:"_JAVA_OPTIONS=-Dsun.awt.fontconfig=$BINDIR/fontconfig.properties"} \
${env:"LANG=en_US.UTF-8"} \
${env:"LC_ALL=C.UTF-8"}

_DOCS_VARS_FLAG=

_DOCS_COMMON_PROCESS_DEPS=

_DOCS_YFM_OUTPUT_FORMAT=
_DOCS_YFM_BOOK_OUTPUT_FORMAT=--output-format html --allowHTML
_DOCS_YFM_LIB_OUTPUT_FORMAT=--output-format md --add-map-file
_DOCS_YFM_BOOK_PROCESS_DEPS=${cwd:ARCADIA_BUILD_ROOT} $YMAKE_PYTHON ${input:"build/scripts/extract_docs.py"} --skip-prefix $ARCADIA_BUILD_ROOT --dest-dir $BINDIR/__s ${rootrel:PEERS}

_DOCS_COMMON_CMDLINE_PREFIX=\
${cwd:ARCADIA_ROOT} $FS_TOOLS copy_all_files $_DOCS_DIR_VALUE $BINDIR/__s $_DOCS_SRCS_VALUE \
&& $_DOCS_COMMON_PROCESS_DEPS \
&& $YMAKE_PYTHON ${input:"build/scripts/copy_files_to_dir.py"} --dest-dir $BINDIR/__s --skip-prefix $ARCADIA_ROOT --skip-prefix $ARCADIA_BUILD_ROOT ${input;context=TEXT:INCLUDE_SRCS}

_DOCS_YFM_BOOK_CMDLINIE=\
$_DOCS_COMMON_CMDLINE_PREFIX \
&& $YMAKE_PYTHON ${input:"build/scripts/stdout2stderr.py"} $YFM_TOOL_RESOURCE_GLOBAL/yfm-docs --input $BINDIR/__s --output $BINDIR/__docsbuild $_DOCS_VARS_FLAG $_DOCS_YFM_OUTPUT_FORMAT --config ${input:CONFIG} $_DOCS_EXTRA_TOOLS ${hide;input:EXTRA_INPUTS} $_DOCS_ENV \
&& $YMAKE_PYTHON ${input:"build/scripts/tar_sources.py"} --output $TARGET --input $BINDIR/__docsbuild $_DOCS_KV

# tag:internal tag:docs
macro _DOCS_YFM_BOOK_IMPL(CONFIG, INCLUDE_SRCS[], EXTRA_INPUTS[]) {
    .CMD=$_DOCS_YFM_BOOK_CMDLINIE
}

_DOCS_YFM_CMD=$_DOCS_YFM_BOOK_IMPL($_DOCS_CONFIG_VALUE INCLUDE_SRCS $_DOCS_INCLUDE_SOURCES_VALUE EXTRA_INPUTS $_DOCS_EXTRA_INPUTS)

_DOCS_MKDOCS_CMDLINE_SUFFIX=
_DOCS_MKDOCS_BOOK_CMDLINE_SUFFIX=${pre=--dep ;ext=preprocessed.tar.gz:PEERS}
_DOCS_MKDOCS_LIB_CMDLINE_SUFFIX=--preprocess-md-only

_DOCS_MKDOCS_CMDLINIE=\
$_DOCS_COMMON_CMDLINE_PREFIX \
&& ${cwd:BINDIR} $YMAKE_PYTHON ${input:"build/scripts/mkdocs_builder_wrapper.py"} $ARCADIA_BUILD_ROOT ${tool:"tools/mkdocs_builder"} --docs-dir $BINDIR/__s --output-tar $TARGET --config ${input:CONFIG} $_DOCS_VARS_FLAG $_DOCS_MKDOCS_CMDLINE_SUFFIX $_DOCS_EXTRA_TOOLS ${hide;input:EXTRA_INPUTS} $_DOCS_ENV $_DOCS_KV

macro _DOCS_MKDOCS_CMD_IMPL(CONFIG, INCLUDE_SRCS[], EXTRA_INPUTS[]) {
    .CMD=$_DOCS_MKDOCS_CMDLINIE
}

_DOCS_MKDOCS_CMD=$_DOCS_MKDOCS_CMD_IMPL($_DOCS_CONFIG_VALUE INCLUDE_SRCS $_DOCS_INCLUDE_SOURCES_VALUE)

_DOCS_YFM_DEFAULT_CONFIG=$MODDIR/.yfm
_DOCS_MKDOCS_DEFAULT_CONFIG=$MODDIR/mkdocs.yml

# tags:docs
### This module is intended for internal use only. Common parts for DOCS and MKDOCS multimodules
### should be defined here.
module _DOCS_BARE_UNIT: _BARE_UNIT {
    .ALLOWED=DOCS_DIR DOCS_CONFIG DOCS_VARS
    .CMD=TOUCH_DOCS_MF
    .FINAL_TARGET=no

    ENABLE(_DOCS_BARE_UNIT)

    SET(MODULE_SUFFIX .tar.gz)
    SET(MODULE_LANG DOCS)
    DEFAULT(_DOCS_DIR_VALUE ${MODDIR})
}

# tag:docs
### This module is intended for internal use only. Common parts for submodules of DOCS multimodule
### should be defined here.
module _DOCS_BASE_UNIT: _DOCS_BARE_UNIT {
    ENABLE(_DOCS_BASE_UNIT)

    DEFAULT(_DOCS_BUILDER_VALUE yfm)
    PEERDIR+=build/platform/yfm
    _DOCS_DEFAULT_CONFIG=$_DOCS_YFM_DEFAULT_CONFIG
    _DOCS_COMMON_BOOK_PROCESS_DEPS=$_DOCS_YFM_BOOK_PROCESS_DEPS
}

# tag:internal tag:docs
### _DOCS_EPILOOGUE() # internal
###
### This macro executes macros which should be envoked after all user
### specified macros in the ya.make file
macro _DOCS_EPILOGUE() {
    SET(_DOCS_BUILDER $_DOCS_BUILDER_VALUE)

    _LATE_GLOB(_DOCS_SRCS_GLOB ${pre=${ARCADIA_ROOT}/;suf=/**/*:_DOCS_DIR_VALUE})
    SET(_DOCS_SRCS_VALUE \${input;hide:_DOCS_SRCS_GLOB})
}

# tag:internal tag:docs
### _DOCS_YFM_USE_PLANTUML() # internal
###
### This macr sets appropriate dependencies for use of plantuml plugin
macro _DOCS_YFM_USE_PLANTUML() {
    PEERDIR(build/platform/java/jdk contrib/java/openjdk-fontconfig)
    COPY_FILE(${ARCADIA_BUILD_ROOT}/contrib/java/openjdk-fontconfig/fontconfig.properties fontconfig.properties)
    SET_APPEND(_DOCS_EXTRA_TOOLS \${hide;tool:"contrib/tools/plantuml"})
    SET_APPEND(_DOCS_EXTRA_INPUTS fontconfig.properties)
    # It's rather strange that a commented statement below doesn't work
    # SET_APPEND(_DOCS_ENV ${_DOCS_PLANTUML_ENV})
    when ($_DOCS_USE_PLANTUML) {
        _DOCS_ENV+=$_DOCS_PLANTUML_ENV
    }
}

# tag:docs
### @usage: DOCS()
###
### Documentation project multimodule.
###
### When built directly, via RECURSE, DEPENDS or BUNDLE the output artifact is docs.tar.gz with statically generated site.
### When PEERDIRed from other DOCS() module behaves like a UNION (supplying own content and dependencies to build target).
### Peerdirs from modules other than DOCS are not accepted.
### Most usual macros are not accepted, only used with the macros DOCS_DIR(), DOCS_CONFIG(), DOCS_VARS(), DOCS_BUILDER().
###
### @see: [DOCS_DIR()](#macro_DOCS_DIR), [DOCS_CONFIG()](#macro_DOCS_CONFIG), [DOCS_VARS()](#macro_DOCS_VARS), [DOCS_BUILDER()](#macro_DOCS_BUILDER).
multimodule DOCS {
    module DOCSBOOK: _DOCS_BASE_UNIT {
        .CMD=_DOCS_YFM_CMD
        .EPILOGUE=_DOCS_EPILOGUE
        .FINAL_TARGET=yes
        .PEERDIR_POLICY=as_build_from

        ENABLE(DOCSBOOK)

        SET(MODULE_TYPE PROGRAM)
        SET(PEERDIR_TAGS DOCSLIB)
        SET(MODULE_TAG DOCSBOOK)

        _DOCS_YFM_OUTPUT_FORMAT=$_DOCS_YFM_BOOK_OUTPUT_FORMAT
        _DOCS_COMMON_PROCESS_DEPS=$_DOCS_COMMON_BOOK_PROCESS_DEPS

        PROCESS_DOCS()
    }

    module DOCSLIB: _DOCS_BASE_UNIT {
        .CMD=_DOCS_YFM_CMD
        .EPILOGUE=_DOCS_EPILOGUE
        .PEERDIR_POLICY=as_include

        ENABLE(DOCSLIB)

        SET(MODULE_TYPE LIBRARY)
        SET(PEERDIR_TAGS DOCSLIB)
        SET(MODULE_TAG DOCSLIB)

        REALPRJNAME=preprocessed

        _DOCS_YFM_OUTPUT_FORMAT=$_DOCS_YFM_LIB_OUTPUT_FORMAT

        PROCESS_DOCS()
    }
}

# tag:docs
### This module is intended for internal use only. Common parts for submodules of MKDOCS multimodule
### should be defined here.
module _MKDOCS_BASE_UNIT: _DOCS_BARE_UNIT {
    .RESTRICTED=DOCS_BUILDER

    ENABLE(_MKDOCS_BASE_UNIT)

    DOCS_CONFIG($_DOCS_MKDOCS_DEFAULT_CONFIG)
}

# tag:internal tag:docs
### _MKDOCS_EPILOOGUE() # internal
###
### This macro executes macros which should be envoked after all user
### specified macros in the ya.make file
macro _MKDOCS_EPILOGUE() {
    _LATE_GLOB(_DOCS_SRCS_GLOB ${pre=${ARCADIA_ROOT}/;suf=/**/*:_DOCS_DIR_VALUE})
    SET(_DOCS_SRCS_VALUE \${input;hide:_DOCS_SRCS_GLOB})
}

# tag:docs
### @usage: MKDOCS()
###
### Documentation project multimodule.
###
### When built directly, via RECURSE, DEPENDS or BUNDLE the output artifact is docs.tar.gz with statically generated site (using mkdocs as builder).
### When PEERDIRed from other MKDOCS() module behaves like a UNION (supplying own content and dependencies to build target).
### Peerdirs from modules other than MKDOCS are not accepted.
### Most usual macros are not accepted, only used with the macros DOCS_DIR(), DOCS_CONFIG(), DOCS_VARS().
###
### @see: [DOCS_DIR()](#macro_DOCS_DIR), [DOCS_CONFIG()](#macro_DOCS_CONFIG), [DOCS_VARS()](#macro_DOCS_VARS).
multimodule MKDOCS {
    module MKDOCSBOOK: _MKDOCS_BASE_UNIT {
        .CMD=_DOCS_MKDOCS_CMD
        .EPILOGUE=_MKDOCS_EPILOGUE
        .FINAL_TARGET=yes
        .PEERDIR_POLICY=as_build_from

        ENABLE(MKDOCSBOOK)

        SET(MODULE_TYPE PROGRAM)
        SET(PEERDIR_TAGS MKDOCSLIB)
        SET(MODULE_TAG MKDOCSBOOK)

        _DOCS_MKDOCS_CMDLINE_SUFFIX=$_DOCS_MKDOCS_BOOK_CMDLINE_SUFFIX

        PROCESS_MKDOCS()
    }

    module MKDOCSLIB: _MKDOCS_BASE_UNIT {
        .CMD=_DOCS_MKDOCS_CMD
        .EPILOGUE=_MKDOCS_EPILOGUE
        .PEERDIR_POLICY=as_include

        ENABLE(MKDOCSLIB)

        SET(MODULE_TYPE LIBRARY)
        SET(PEERDIR_TAGS MKDOCSLIB)
        SET(MODULE_TAG MKDOCSLIB)

        REALPRJNAME=preprocessed

        _DOCS_MKDOCS_CMDLINE_SUFFIX=$_DOCS_MKDOCS_LIB_CMDLINE_SUFFIX

        PROCESS_MKDOCS()
    }
}

# tag:docs
_DOCS_USE_PLANTUML=
### @usage: USE_PLANTUML()
###
### Use PlantUML plug-in for yfm builder to render UML diagrams into documentation
macro USE_PLANTUML() {
    ENABLE(_DOCS_USE_PLANTUML)
}

# tag:docs
DOCSBUILDER=yfm
### @usage: DOCS_BUILDER(tool)
###
### Specify docs builder tool.
### Avalialbe tools: mkdocs and yfm (by default).
###
### @see: [DOCS](#multimodule_DOCS)
macro DOCS_BUILDER(DocsTool) {
    SET(_DOCS_BUILDER_VALUE $DocsTool)
}

# tag:docs
### @usage: DOCS_DIR(path)
###
### Specify directory with source .md files for DOCS multimodule if it differs from project directory.
### Path must be Arcadia root relative.
###
### @see: [DOCS](#multimodule_DOCS)
macro DOCS_DIR(Dir) {
    SET(_DOCS_DIR_VALUE $Dir)
}

# tag:docs
_DOCS_DEFAULT_CONFIG=
_DOCS_CONFIG_VALUE=$_DOCS_DEFAULT_CONFIG
### @usage: DOCS_CONFIG(path)
###
### Specify path to config file for DOCS multimodule if it differs from default path.
### If [DOCS_BUILDER()](#macro_DOCS_BUILDER) is set to "mkdocs" the default path is "%%project_directory%%/mkdocs.yml".
### If [DOCS_BUILDER()](#macro_DOCS_BUILDER) is not set or set to "yfm" the default path is "%%project_directory%%/.yfm".
### Path must be either Arcadia root relative.
###
### @see: [DOCS](#multimodule_DOCS)
macro DOCS_CONFIG(File) {
    SET(_DOCS_CONFIG_VALUE $File)
}

# tag:docs
_DOCS_VARS_VALUE=
### @usage: DOCS_VARS(variable1=value1 variable2=value2 ...)
###
### Specify a set of default values of template variables for DOCS multimodule.
### There must be no spaces around "=". Values will be treated as strings.
###
### @see: [DOCS](#multimodule_DOCS)
macro DOCS_VARS(Args...) {
    SET_APPEND(_DOCS_VARS_VALUE $Args)
}

# tag:docs
_DOCS_INCLUDE_SOURCES_VALUE=
### @usage: DOCS_INCLUDE_SOURCES(path...)
###
### Specify a list of paths to source code files which will be used as text includes in a documentation project.
### Paths must be Arcadia root relative.
###
### @see: [DOCS](#multimodule_DOCS)
macro DOCS_INCLUDE_SOURCES(Args...) {
    SET_APPEND(_DOCS_INCLUDE_SOURCES_VALUE $Args)
}