ru.vyarus.gradle.plugin.mkdocs.task.MkdocsTask.groovy Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of gradle-mkdocs-plugin Show documentation
Mkdocs documentation plugin
There is a newer version: 4.0.1
package ru.vyarus.gradle.plugin.mkdocs.task

import groovy.transform.CompileStatic
import org.gradle.api.GradleException
import org.gradle.api.tasks.Internal
import org.gradle.api.tasks.Nested
import org.gradle.api.tasks.Optional
import ru.vyarus.gradle.plugin.mkdocs.MkdocsExtension
import ru.vyarus.gradle.plugin.mkdocs.util.MkdocsConfig
import ru.vyarus.gradle.plugin.python.task.PythonTask

/**
 * General mkdocs task.
 * 
 * Provides support for gradle-driven variables. When variables be declared in {@code mkdocs.extras} map,
 * task would generate special data file: {@code [mkdocs.yml location]/docs/_data/gradle.yml}.
 * Markdownextradata plugin must be activated in mkdocs.yml (exception will be thrown if not). Plugin searches
 * by default in @{code [mkdocs.yml location]/docs/_data/} dir for variable files (no magic behaviour).
 * In documentation variables may be used as 
{{ gradle.var_name }}.
 *
 * @author Vyacheslav Rusakov
 * @since 13.11.2017
 * @see markdownextradata plugin documentation
 */
@CompileStatic
class MkdocsTask extends PythonTask {

    /**
     * Extra gradle-provided variables to use in documentation.
     */
    @Nested
    @Optional
    Map extras

    @Override
    @SuppressWarnings('UnnecessaryGetter')
    void run() {
        if (getExtras() == null || getExtras().isEmpty()) {
            // no vars - simple run
            super.run()
        } else {
            runWithVariables()
        }
    }

    @Override
    @SuppressWarnings('GetterMethodCouldBeProperty')
    String getModule() {
        // restrict commands to mkdocs module
        return 'mkdocs'
    }

    /**
     * For use in specialized tasks.
     *
     * @return mkdocs extension object
     */
    @Internal
    protected MkdocsExtension getExtension() {
        project.extensions.findByType(MkdocsExtension)
    }

    private void runWithVariables() {
        File data = resolveDataDir()
        boolean removeDataDir = !data.exists()
        File gen = new File(data, 'gradle.yml')
        try {
            if (removeDataDir) {
                data.mkdir()
            }
            // assuming this file owned by gradle exclusively and may remain only because of incorrect task shutdown
            if (gen.exists()) {
                gen.delete()
            }
            logger.lifecycle('Generating mkdocs data file: {}', getFilePath(gen))
            String report = ''
            gen.withWriter { BufferedWriter writer ->
                getExtras().each { k, v ->
                    // Object value used for deferred evaluation (GString may use lazy placeholders)
                    String line = k.replaceAll('[ -]', '_') + ': ' + (v ?: '')
                    writer.writeLine(line)
                    report += "\t$line\n"
                }
            }
            logger.lifecycle(report)
            super.run()
        } finally {
            gen.delete()
            if (removeDataDir) {
                data.delete()
            }
        }
    }

    private File resolveDataDir() {
        MkdocsConfig config = new MkdocsConfig(project, extension.sourcesDir)

        if (!config.contains('plugins.markdownextradata')) {
            throw new GradleException(
                    'Gradle-defined extra properties require \'markdownextradata\' plugin active in ' +
                            'your mkdocs.yml file, which is currently not the case. \nEither remove extra properties ' +
                            'declaration (in build.gradle) or declare plugin (in mkdocs.yml) like this: \n' +
                            'plugins:\n' +
                            '   - search\n' +
                            '   - markdownextradata')
        }

        // mkdocs.yml location
        File root = project.file(extension.sourcesDir)

        // configuration may override default "docs" location
        String docsPath = config.find('docs_dir') ?: 'docs'
        File docs = new File(docsPath)
        // docs_dir config value may contain absolute path declaration
        if (!docs.absolute) {
            docs = new File(root, docs.path)
        }
        if (!docs.exists()) {
            // documentation sources dir must be present (catches misconfiguration)
            throw new GradleException(
                    "Mkdocs documentation sources directory not found: ${getFilePath(docs)}")
        }

        return new File(docs, '_data')
    }

    /**
     * Looks if file inside project and relative path would be reasonable, otherwise return absolute path.
     *
     * @param file file
     * @return relative or absolute file path
     */
    private String getFilePath(File file) {
        if (file.path.startsWith(project.rootDir.path)) {
            return project.relativePath(file)
        }
        return file.absolutePath
    }
}