OptaPlanner logo
  • Download
  • Learn
    • Documentation
    • Videos
    • Slides
    • Training

    • Use cases
    • Compatibility
    • Testimonials and case studies
  • Get help
  • Blog
  • Source
  • Team
  • Services
  • KIE
    • Drools
    • OptaPlanner
    • jBPM
    • Kogito
  • Star
  • T
  • L
  • F
  • YT
Fork me on GitHub

OptaPlanner documentation turns over a new leaf

Tue 26 October 2021
Avatar Radovan Synek
Radovan Synek

GitHub

OptaPlanner developer

For years, OptaPlanner has been offering the documentation in two formats: single-page HTML and PDF. This now changes with the launch a new documentation website, built using Antora.

What’s so exciting about the new documentation?

First and foremost, it loads instantly as opposed to the old single-page HTML documentation. For example, if I want to read about repeated planning, I open the single-page HTML docs and wait nearly half a minute for the page to load, despite having a very good cable connection. With the new documentation, it took me only 2 seconds as each chapter has its own HTML page and thus the content that has to be loaded is limited.

This also means it’s now easier to effectively share links to a particular section.

Second, now you can search through the entire docs:

Search in the docs

The search box at the top of the page shows suggestions as soon as you start typing. Each suggestion consists of the chapter and a link to where the search term occurs.

Third, if you spot a discrepancy in the documentation and would like to improve it, contributing was never easier:

Edit the docs

Finally, this new documentation website is much friendlier to search engines, which should make it show up in Google search results more often than before.

Building the documentation website

The documentation sources remain in the optaplanner-docs module in the optaplanner repository, but the website assembly, named optaplanner-website-docs, became a part of the optaplanner-website:

optaplanner-website directory structure

Similarly to the entire optaplanner-website, the optaplanner-website-docs is built using Maven. The Maven module acts as a wrapper over Antora, which generates the static site from AsciiDoc sources.

There are two Antora playbooks referring to documentation sources. The first one, used by default, is antora-playbook.yml that refers to the latest OptaPlanner release.

...
content:
  edit_url: '{web_url}/edit/main/{path}'
  sources:
    - url: git@github.com:kiegroup/optaplanner.git
      # Updates with every release to point to the latest release branch.
      branches: [8.12.x]
      start_path: optaplanner-docs/src
...

To render the latest documentation:

  1. cd optaplanner-website/optaplanner-website-docs

  2. mvn clean package

  3. Open the index.html located in target/website/docs in your browser.

The second Antora playbook, antora-playbook-author.yml, is activated by the author maven profile and refers to the current optaplanner local Git repository HEAD.

...
content:
  edit_url: '{web_url}/edit/main/{path}'
  sources:
    # Assuming the optaplanner local repository resides next to the optaplanner-website.
    - url: ../../optaplanner
      branches: [HEAD]
      start_path: optaplanner-docs/src
...

To preview local changes in the documentation:

  1. Make sure the optaplanner and optaplanner-website Git repositories are located in the same directory or change the local URL accordingly.

  2. cd optaplanner-website/optaplanner-website-docs

  3. mvn clean package -Pauthor

  4. Open the index.html located in target/website/docs in your browser.

Supported documentation formats

Introducing new formats does not have to result in abandoning the old ones, and in our case it does not. While I encourage everyone to visit the new documentation website, the existing formats continue to be published with every release as before.

Also, should you need to have a look at a particular version of the documentation, it’s still at your hand in the archive.

Conclusion

Since the 8.12.0.Final release, there is a new documentation website available under https://www.optaplanner.org/docs. The documentation is now structured into pages by chapters and searchable. The single-page HTML and PDF documentation remains available for every release.


Permalink
 tagged as documentation website

Comments

Visit our forum to comment
AtomNews feed
Don’t want to miss a single blog post?
Follow us on
  • T
  • L
  • F
Blog archive
Latest release
  • 8.20.0.Final released
    Thu 14 April 2022
Upcoming events
    Add event / Archive
Latest blog posts
  • Real-time planning meets SolverManager
    Mon 7 March 2022
    Radovan Synek
  • OptaPlanner documentation turns over a new leaf
    Tue 26 October 2021
    Radovan Synek
  • Order picking optimization in warehouses and supermarkets with OptaPlanner
    Thu 14 October 2021
    Walter Medvedeo
  • Monitor OptaPlanner solvers through Micrometer
    Tue 12 October 2021
    Christopher Chianelli
  • A new AI constraint solver for Python: OptaPy
    Tue 5 October 2021
    Christopher Chianelli
  • How much faster is Java 17?
    Wed 15 September 2021
    Geoffrey De Smet
  • Constraint Streams get some more love
    Thu 19 August 2021
    Lukáš Petrovický
  • Blog archive
Latest videos
  • Host your OptaPlanner app on OpenShift (Kubernetes)
    Mon 7 February 2022
    Geoffrey De Smet
  • OptaPlanner - A fast, easy-to-use, open source AI constraint solver for software developers
    Mon 31 January 2022
  • Order picking planning with OptaPlanner
    Fri 31 December 2021
    Anna Dupliak
  • AI lesson scheduling on Quarkus with OptaPlanner
    Thu 18 November 2021
    Geoffrey De Smet
  • Maintenance scheduling
    Fri 12 November 2021
    Geoffrey De Smet
  • Optimized order picking in warehouses and supermarkets
    Tue 26 October 2021
    Walter Medvedeo
  • A modern OO/FP constraint solver
    Tue 14 September 2021
    Geoffrey De Smet
  • Video archive

OptaPlanner is open. All dependencies of this project are available under the Apache Software License 2.0 or a compatible license. OptaPlanner is trademarked.

This website was built with JBake and is open source.

Community

  • Blog
  • Get Help
  • Team
  • Governance
  • Academic research

Code

  • Build from source
  • Issue tracker
  • Release notes
  • Upgrade recipes
  • Logo and branding

KIE projects

  • Drools rule engine
  • OptaPlanner constraint solver
  • jBPM workflow engine
  • Kogito Business Automation platform
CC by 3.0 | Privacy Policy
Sponsored by Red Hat