Converting to documentation / book

[designpatternsphp]

Converting to documentation / book

[eddiejaoude]

What would be good, is if there was a markdown -> docs library that allowed referencing to the php files in the markdown & automatically included the code so there was no duplication.

[aik099]

Then migrating to ReadTheDocs.org would be right way IMO. It will automatically create table of contents and PDF versions of documentation. The only manual work is transforming Markdown files into RST files.

[eddiejaoude]

Then migrating to ReadTheDocs.org would be right way...

Yes that would be a better idea 👍

[eddiejaoude]

According to the docs of RTD, it can use Markdown https://read-the-docs.readthedocs.org/en/latest/getting_started.html#in-markdown

[aik099]

It can, but that seriously limits set of features you can use.

[eddiejaoude]

seriously limits set of features you can use

I was just trying to read up on the limitations/differences. Thanks for clarifying 😄

[aik099]

Originally ReadTheDocs.org was a Front-End for Sphynx generated documentation (only supported RST). Over time support for other file formats was added.

If you'd like to send a PR using https://github.com/aik099/phpunit-mink/tree/master/docs might give you a head start.

[eddiejaoude]

Thanks I will take a look 👍

[eddiejaoude]

I started to have a play...

https://github.com/eddiejaoude/DesignPatternsPHP

[aik099]

You can also use theme from ReadTheDocs to make it look exactly like there.

Here are instructions on how to install it locally: https://github.com/qa-tools/qa-tools/tree/read-the-docs/docs
Here is relevant piece of config: https://github.com/qa-tools/qa-tools/blob/read-the-docs/docs/conf.py#L10-L15

[eddiejaoude]

Nice one! 👍

[aik099]

Now you see why theme matters. Apparently ReadTheDocs.org theme uses only 2 levels of Toc and that's why left sidebar is empty.

[aik099]

I'd recommend you go and celebrate New Year instead of doing all of that right now 😉

[eddiejaoude]

Haha thanks... I am. You too. Thanks :-)

Chat in 2015

Sent from my iPhone

On 31 Dec 2014, at 23:24, Alexander Obuhovich [email protected] wrote:

I'd recommend you go and celebrate New Year instead of doing all of that right now

—
Reply to this email directly or view it on GitHub.

[eddiejaoude]

Hope you had a good New Years eve!

How do I do a link without specifying the extension? eg. if I specify the extension rst & generate html, then it won't work, if I specify the extension html it works but I feel that is wrong?

[aik099]

How do I do a link without specifying the extension? eg. if I specify the extension rst & generate html, then it won't work, if I specify the extension html it works but I feel that is wrong?

By default if you create an internal link, then it is assumed to be in RST format and extension isn't required.
Here is how to create external links: http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-targets

Google is pretty good at searching RST documentation by the way as well.

[eddiejaoude]

Google is pretty good at searching RST documentation by the way as well.

I wasn't being lazy, I did have a look, but with or without the rst extension it didn't work (only with html extension).

I looked at the following docs:
http://sphinx-doc.org/rest.html#hyperlinks
http://sphinx-doc.org/markup/inline.html#ref-role

I will research more, sorry to trouble you 😄

[eddiejaoude]

I needed to use :doc: instead of :ref:. Easy when you know how 😉

[aik099]

I you would like to create PR with your existing progress, then I can take a look at it. It's pretty hard without actually seeing RST content you're talking about. Just add [WIP] before PR title (means work in progress).

[eddiejaoude]

Sure #115

[fhferreira]

+1

[eddiejaoude]

As this is now done, I am going to close this ticket. Great work all involved 👍