Investigate alternatives for DocBook XML/XSL

[sebastianbergmann]

GitBook (http://www.gitbook.io/) would allow us to write the PHPUnit documentation using Markdown and convert it to a complete static website. This would make the workflow to contribute to and collaborate on the documentation easier.

[whatthejeff]

Looks very promising. I might be able to take a stab at porting stuff this weekend if no one gets to it first.

[whatthejeff]

The editor looks really cool too: https://github.com/GitbookIO/editor

[whatthejeff]

One thing I noticed is that there doesn't seem to be a standard way for versioning the books like we do with our current docs. I guess we could manage versioning outside of gitbook, though.

[sun]

Looks awesome. I assume the idea is to still host the static books on phpunit.de and not on gitbook.io, right?

If so, I think we'd keep the current file structure for the most part, and the docs would still be separate per PHPUnit version. We can inject the links to other versions either via node.js, or perhaps even entirely via JS in the front-end.

Pandoc may be able to convert all DocBook XML documents into Markdown and appears to be the go-to solution for this task; here's a seemingly useful Pandoc tutorial for DocBook.

progit-to-gitbook is a sample conversion script, which might have helpful code to borrow from (although the original source was in Markdown already).

GitBook has one conceptual difference compared to now: Every chapter is a separate page, including sub-chapters. I like how the current manual splits only the main chapters onto separate pages, exposing sub-chapters as jump link targets on the same page. Only the manual's current navigation is suboptimal; Bootstrap's sticky Affix navigation would be plain awesome (+ there's a gitbook-plugin-bootstrapjs).

The trickiest part may be to ensure that existing links to the manual on the net won't break by this; however, it seems like all current manual pages are /[slug].html and GitBook's generated static HTML page are, too.

That said, Markdown does not support custom jump link anchors; they're auto-generated from the text in a heading. So unless there is a custom gitbook or marked plugin for that, most jump link anchors are going to differ/break.

[sun]

Closely related question: Do we really need the manual separately for every minor version? Wouldn't a single per major version be sufficient (i.e., 4.x, 3.x)? And instead, add "since" markers where necessary (just like @since in code)?

[sebastianbergmann]

That was discussed in #104. I still think that the benefit of versioned documentation does not justify the effort involved and agree that "since" markers should be enough.

[sun]

Btw, GitHub Pages updated to Jekyll 2.2.0 today. This allows you to do quite some amazing things with GitHub Pages in the gh-pages branch (without having to build/commit any static files), which could be a feasible alternative to depending on the GitBook framework.

[whatthejeff]

@sun Yeah, I saw that. Definitely something to investigate.

[whatthejeff]

@sun @sebastianbergmann I'm actually a fan of versioned docs (just in general), but "since" markers and notes would probably be adequate for PHPUnit.

[sun]

@whatthejeff I didn't mean to remove versioning altogether. What I meant was to limit the manual to major versions only. Only within a minor version "since" markers would be used (+ it would be good to remove all of them when forking to a new major, so as to remove visual clutter, because it's pointless to indicate that assertFoo() exists since 3.2 if you're looking at the manual for 4.x).

[whatthejeff]

@sun Yeah, I understood. I'm not against that idea either :)

[sebastianbergmann]

Another option could be https://read-the-docs.readthedocs.org/en/latest/getting_started.html

[sun]

Yup, Guzzle uses RTD for its manual.

Theoretically it allows to maintain the documentation within the code repo itself (like Guzzle does) - although I'm not sure whether that is a good idea (due to translations, repo size, etc).

While reStructuredText would definitely be an improvement over DocBook XML/XSL, it originates from and is primarily used in Python related projects. At least I'm not aware of many PHP users/developers that are familiar with RST. It's fairly similar to Markdown, so perhaps not a real barrier. At least GitHub's UI natively supports rendering of RST documents.

I don't know how hard it is to install RTD/Sphinx locally (in particular on Windows); I'll try it out. — Making it easy to contribute to the documentation should be a key decision factor; the easier it is, the better will be the docs.

[whatthejeff]

At least I'm not aware of many PHP users/developers that are familiar with RST

I know it's used pretty heavily in the Symfony community.

[sun]

Different consideration: At minimum the Appendix A. Assertions chapter could (should?) be generated from the PHPDoc of the actual code?

It's always Signature/Synopsis, PHPDoc summary, and PHPDoc description with embedded @code/equivalent or @example.
(FWIW, the CLI output example doesn't really add value and isn't worth to keep, IMO.)

Not able to back up this statement, but I'd argue that the most frequently visited/needed documentation pages are the Appendix references about assertions, annotations, and configuration anyway?

Those pages need to be manually kept in sync with the actual code.

So, just to throw in another option… phpDocumentor matured a lot recently and would be able to generate a manual based on the actual code.

AFAIK, it doesn't support translations though, so that would have to be dropped.

Likewise, I don't think it supports @page + @section tags. Over at Drupal, we're using these tags to turn comment-only .api.php files into rich entry point pages to educate about high-level concepts.

That said, I just noticed fellow friends at phpDocumentor started work on Scrybe to produce user manuals including reference documentation (example).

[sebastianbergmann]

We should go with Markdown-based sourcefiles and one version of the manual (instead of one edition of the manual per version of PHPUnit). We might even go as far as making this repository English only and have separate repositories for the translation.

[sebastianbergmann]

Dear contributor,

thanks to the hard work by @belanur, @starikovm, @trueromio, and others, the changes outlined in #471 (comment) have been implemented.

This repository, https://github.com/sebastianbergmann/phpunit-documentation, is now archived and read-only. The documentation for PHPUnit version prior to PHPUnit 7.0 will no longer be changed or updated. It is still hosted at

• Multiple HTML files: https://phpunit.de/manual/6.5/en/index.html
• Multiple HTML files (in a .tar.bz2 archive): https://phpunit.de/manual/current/en/download.tar.bz2
• Single HTML file: https://phpunit.de/manual/current/en/phpunit-book.html
• PDF: https://phpunit.de/manual/current/en/phpunit-book.pdf
• ePub: https://phpunit.de/manual/current/en/phpunit-book.epub

Simply replace 6.5 with the version number you are looking for. Simply replace en with fr, pt_br, ja, or zh_cn to access the French, Brazilian Portuguese, Japanese, or Simplified Chinese translation, respectively.

Starting with the documentation for PHPUnit 7.0, the PHPUnit documentation is hosted at https://phpunit.readthedocs.io/.

• The English documentation for PHPUnit is now maintained in the phpunit-documentation-english project
• The French documentation for PHPUnit is now maintained in the phpunit-documentation-french project
• The Brazilian Portuguese documentation for PHPUnit is now maintained in the phpunit-documentation-brazilian-portuguese project
• The Japanese documentation for PHPUnit is now maintained in the phpunit-documentation-japanese project
• The Simplified Chinese documentation for PHPUnit is now maintained in the phpunit-documentation-chinese project

I am sorry that I have to close this issue here as GitHub does not support moving issues from one project to another. Please open a new ticket for this issue in one of the new issue trackers (see above).