Enhance api doc generator

[cebe]

This is a follow up to #1784 and #62.

• add source code to the templates
• nice to have: add links to source code.
• create online template for yiiframework.com
• create nicer offline template with bootstrap
• verify @inheritDocs works as expected
• cli option to exclude files
• fix markdown renderer to support github code syntax. (waiting for better approach to extending markdown erusev/parsedown#74)

[qiangxue]

How are methods? Should we display each method in a separate page?

[qiangxue]

Or more generally, what kind of pages will we will have?

[cebe]

I thought about making it similar to the current docs, one page per class and navigation to methods and properties via anchors.

btw. do we want to add support for chm? Seen the code for it in 1.1 generator. never used them though.

[qiangxue]

I think we don't need chm, at least not for now.

How about putting the details for each method/property/event in a separate page? This will make it easier for users to add and read comments.

[samdark]

chm is frequently requested.

[samdark]

Structure is perfect in 1.1 API docs.

[qiangxue]

We will provide an online doc viewer, which can replace chm, I think.

[cebe]

what are the benefits of chm over html page like this? http://stuff.cebe.cc/yii2docs/ As far as I understood it is just packed in one file but still browseable html.

[samdark]

@qiangxue the goal of chm is to have offline reference.

@cebe offline.

[cebe]

the set of html generated by the offline template can be used offline ;)

[samdark]

Yes, but:

1. It doesn't have global filtering/search built in.
2. It's a set of files, not just one. A bit less convenient.

[qiangxue]

The online api viewer may support searching. Since php5.4 has a built-in Web, I think as long as you have PHP installed, you should be able to view this online doc.

[samdark]

Ah, you're talking about offline web-served realtime generator?

[qiangxue]

Yes. It's on your local machine. You may view it like a local Web app.

[samdark]

Should be OK then.

[cebe]

Just created a yii2 branch in the website repo and created an online template for the apidoc generator:

./apidoc render path/to/framework/ yiisite/common/data/2.0.0-beta/api --template=online

Everything except search is working.

[dilip-vishwa]

Chm is the best to use as Doc for many reasons such as:

1. search is done on all the words and letter in the docs(very good).
2. very fast.
3. yii1 chm doc is the best doc, I have used in my life.
4. very small size.
5. highlighting of search and many more.
   etc. etc.
   So, we should prefer chm over other, but we can also have multiple docs.(online, etc.).

[cebe]

A new version of API docs including the guide is online at http://stuff.cebe.cc/yii2docs/index.html
This one is based on bootstrap.

[samdark]

Looks great!

[qiangxue]

It looks great to me!
How about breaking the detail view for each method into a separate page? This will make commenting easier.

[lucianobaraglia]

Woow, nice! 😃

But properties reference are killing my eyes...

[qiangxue]

This is invalid reference, I think. @cebe: can you generate a list of such errors so that we can fix them?

[samdark]

Is it true that methods from traits aren't listed?

[cebe]

Is it true that methods from traits aren't listed?

should be listed. See here: http://stuff.cebe.cc/yii2docs/yii_db_activequery.html#methods

This is invalid reference, I think. @cebe: can you generate a list of such errors so that we can fix them?

yep, red and yellow markers are for classes or properties that could not be found.
Will create a check command later that finds such things.

How about breaking the detail view for each method into a separate page? This will make commenting easier.

not sure about this, we'll have many pages. will try to make such a layout an see how it works.

[qiangxue]

not sure about this, we'll have many pages. will try to make such a layout an see how it works.

I'm just trying to follow how PHP organizes its help pages, since we all like its well commented help pages.

[qiangxue]

Another benefit of having separated method pages is that it allows easier integration with IDE (e.g. you want to pop up a help window for a method you are using).

[marsuboss]

Is it possible to sort methods and properties ?

[samdark]

Absolutely possible and I think it should be done.

[cebe]

Is it possible to sort methods and properties ?

sure, committed a change, did not notice it was not sorted yet :)

[cebe]

Just in case someone has some spare time for tedious work:

In yii2 dev repo (git clone https://github.com/yiisoft/yii2 && cd yii2):

cd extensions/apidoc
composer install
./apidoc render ../../framework/ yiidocs --template=bootstrap --guide=../../docs/guide

This will output a list of reference link errors and non documented classes,methods,properties, etc...
Happy fixing!

[cebe]

APIdocs now have proper markdown parsing and simple code highlighting through php highlight_string function.
Currently working on the edge with unmerged upstream pull requests to the markdown parser so the tool might not work for you.
http://stuff.cebe.cc/yii2docs/guide_active-record.html

[samdark]

It seems it doesn't display images.

[cebe]

Can you show an example link?

[samdark]

http://stuff.cebe.cc/yii2docs/guide_apps-advanced.html

[cebe]

fixed. should be up to date in 15min

[cebe]

API doc generator is done.