Giter Club home page Giter Club logo

docs-maven-skin's Introduction

Docs Maven Skin

A minimalist and responsive Bootstrap-based HTML5 skin for Maven Site, which will help to create documentation sites with Maven.

It is easy to use, just remember to check the project documentation to find out how to set it up, and also to find out how the skin looks in an actual Maven Site. New projects may as well make use of the Library Maven Archetype which, among other features, takes advantage of this skin and shows how to set it up.

The skin has been adapted from the static template Docs Bootstrap Template, which will be the visual reference to be followed by this project.

Maven support: the skin only supports the Maven Site Plugin 3.6 onwards, due to changes to the way the velocity tools are loaded.

Maven Central

Release docs Development docs

Features

Demo

The project documentation makes use of the skin, it is always built with the latest release available. You can check the links just below this section.

Documentation

Documentation is always generated for the latest release, kept in the 'master' branch:

Documentation is also generated from the latest snapshot, taken from the 'develop' branch:

The documentation site sources come along the source code (as it is a Maven site), so it is always possible to generate them using the following Maven command:

mvn verify site

The verify phase is required, as otherwise some of the reports won't be created.

Acknowledgement

The project started as a fork of the Reflow Maven Skin, but it quickly became its own thing. Still, it owes much to that project.

Usage

As any Maven Skin it is handled through the Maven Plugin. Check the docs for more concrete information.

Prerequisites

As a Maven Skin, the project requirements are very specific:

  • Maven
  • Maven Site plugin (>=3.6)
  • Maven Site enabled

Installing

The recommended way to install the project is by setting up your preferred dependencies manager. To get the configuration information for this check the Maven Central Repository.

If for some reason manual installation is necessary, use the usual Maven installation command:

mvn install

Reducing the Dependency Scope

There is no need to add the skin as a dependency for the full project. Just add it to the Maven site plugin:

<build>
    <plugins>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <dependencies>
                ...
                <dependency>
                    <!-- Docs Maven Skin -->
                    <groupId>com.bernardomg.maven.skins</groupId>
                    <artifactId>docs-maven-skin</artifactId>
                    <version>${site.skin.version}</version>
                </dependency>
                ...
            </dependencies>
            ...
        </plugin>
        ...
    </plugins>
</build>

Setting Up the Skin

Register the skin into the site.xml file:

<skin>
    <groupId>com.bernardomg.maven.skins</groupId>
    <artifactId>docs-maven-skin</artifactId>
    <version>[current version]</version>
</skin>

Afterwards the skin will be used when generating the site.

More detailed information can be found in the documentation. Including information for changing the theme.

Running Tests

Integration tests are included in the project to verify various configurations. These can be run by using the usual Maven command:

mvn verify

They are run by using the Maven Invoker Plugin, and the configurations are included in the 'src/it' folder.

Pay attention that the results from generating these tests are copied to the generated Maven Site by the Maven Resources Plugin.

If using Eclipse the tests may not run, due to an incompatibility with the invoker. It is recommender running the tests through command line.

Collaborate

Any kind of help with the project will be well received, and there are two main ways to give such help:

  • Reporting errors and asking for extensions through the issues management
  • or forking the repository and extending the project

Issues Management

Issues are managed at the GitHub project issues tracker, where any GitHub user may report bugs or ask for new features.

Getting the Code

If you wish to fork or modify the code, visit the GitHub project page, where the latest versions are always kept. Check the 'master' branch for the latest release, and the 'develop' for the current, and stable, development version.

License

The project has been released under the MIT License.

docs-maven-skin's People

Contributors

alxn avatar andrebiegel avatar bernardo-mg avatar ghunteranderson avatar okorz001 avatar ordiel avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

docs-maven-skin's Issues

Tags reports creates empty headings

The tags list report is creating an empty h3 heading. Probably it should contain the name of a tag, but for some reason it is just empty.

Minify files

The CSS and JS files can be minified and used that way.

Headings are, randomly, not being created from the markdown files

Sometimes the markdown level 1 headings are not being created from the markdown files.

For example this may not work:

Heading

Instead of creating an equivalent HTML heading it is shown as written.

The direct way to fix this seems to be removing the space between the # and the text, like this:
#Heading

But this does not fix the actual problem, as the reason for this behaviour is unknown.

Add Velocity and HTML code validation

Maybe the Velocity template can be processed through Velocity, and then the resulting page validated with HTML Soup or similar. This way the project would include tests validating page creation.

The team page is missing ids

No ids are generated on the team page, meaning that team members can't be linked, for example in the changes log.

Trying to use a missing constant in the metadata

The site metadata is using a constant which is not always set.

This happens in the following line:

<meta property="og:url" content="$config.canonicalLink.getValue()"/>

Check if the constants exist before building the metadata blocks.

Add option for URLs list

It can be nice having support for a collection of external URLs, for example to the Openhub page, or to related projects.

Add support for external reports

Links to reporting services such as version eye or coveralls could be added to the reports page.

This would require a list of external reports, including URL and name.

Improve site generation tests

The site generation tests make use of Groovy in a simple way. Just looking for strings.

Instead they should try to validate the HTML code, maybe by using JSoup.

Images are not being transformed into figures

The skin is meant to transform the images on the main section into figures, which will have the alternate text as the figure caption, but this is not happening, and instead the img element by itself is being used.

Fix the remaining reports

Several reports are not correctly formatted. Mostly they are starting with a level 2 heading, and not a level 1 heading.

Format HTML

After generating the pages the HTML code should be formatted. This is to make the code pretty and readable.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.