New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhance api doc generator #1797

Closed
cebe opened this Issue Jan 6, 2014 · 36 comments

Comments

Projects
None yet
6 participants
@cebe
Member

cebe commented Jan 6, 2014

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 erusev/parsedown#74)

@ghost ghost assigned cebe Jan 6, 2014

@qiangxue

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 6, 2014

Member

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

Member

qiangxue commented Jan 6, 2014

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

@qiangxue

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 6, 2014

Member

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

Member

qiangxue commented Jan 6, 2014

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

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 6, 2014

Member

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.

Member

cebe commented Jan 6, 2014

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

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 6, 2014

Member

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.

Member

qiangxue commented Jan 6, 2014

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

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 6, 2014

Member

chm is frequently requested.

Member

samdark commented Jan 6, 2014

chm is frequently requested.

@samdark

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 6, 2014

Member

Structure is perfect in 1.1 API docs.

Member

samdark commented Jan 6, 2014

Structure is perfect in 1.1 API docs.

@qiangxue

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 6, 2014

Member

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

Member

qiangxue commented Jan 6, 2014

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

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 6, 2014

Member

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.

Member

cebe commented Jan 6, 2014

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

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 6, 2014

Member

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

@cebe offline.

Member

samdark commented Jan 6, 2014

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

@cebe offline.

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 6, 2014

Member

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

Member

cebe commented Jan 6, 2014

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

@samdark

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 6, 2014

Member

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.
Member

samdark commented Jan 6, 2014

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

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 6, 2014

Member

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.

Member

qiangxue commented Jan 6, 2014

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

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 6, 2014

Member

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

Member

samdark commented Jan 6, 2014

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

@qiangxue

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 6, 2014

Member

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

Member

qiangxue commented Jan 6, 2014

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

@samdark

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 6, 2014

Member

Should be OK then.

Member

samdark commented Jan 6, 2014

Should be OK then.

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 23, 2014

Member

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.

Member

cebe commented Jan 23, 2014

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

This comment has been minimized.

Show comment
Hide comment
@dilip-vishwa

dilip-vishwa Jan 23, 2014

Contributor

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.).
Contributor

dilip-vishwa commented Jan 23, 2014

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 added a commit that referenced this issue Jan 23, 2014

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 24, 2014

Member

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.

Member

cebe commented Jan 24, 2014

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

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 24, 2014

Member

Looks great!

Member

samdark commented Jan 24, 2014

Looks great!

@qiangxue

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 24, 2014

Member

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

Member

qiangxue commented Jan 24, 2014

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

@lucianobaraglia

This comment has been minimized.

Show comment
Hide comment
@lucianobaraglia

lucianobaraglia Jan 24, 2014

Contributor

Woow, nice! 😃

But properties reference are killing my eyes...

yii framework 2 0 documentation 2014-01-24 12-33-15

Contributor

lucianobaraglia commented Jan 24, 2014

Woow, nice! 😃

But properties reference are killing my eyes...

yii framework 2 0 documentation 2014-01-24 12-33-15

@qiangxue

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 24, 2014

Member

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

Member

qiangxue commented Jan 24, 2014

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

@samdark

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 24, 2014

Member

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

Member

samdark commented Jan 24, 2014

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

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 24, 2014

Member

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.

Member

cebe commented Jan 24, 2014

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

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 24, 2014

Member

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.

Member

qiangxue commented Jan 24, 2014

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

This comment has been minimized.

Show comment
Hide comment
@qiangxue

qiangxue Jan 24, 2014

Member

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).

Member

qiangxue commented Jan 24, 2014

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

This comment has been minimized.

Show comment
Hide comment
@marsuboss

marsuboss Jan 28, 2014

Contributor

Is it possible to sort methods and properties ?

Contributor

marsuboss commented Jan 28, 2014

Is it possible to sort methods and properties ?

@samdark

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 28, 2014

Member

Absolutely possible and I think it should be done.

Member

samdark commented Jan 28, 2014

Absolutely possible and I think it should be done.

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 28, 2014

Member

Is it possible to sort methods and properties ?

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

Member

cebe commented Jan 28, 2014

Is it possible to sort methods and properties ?

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

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 28, 2014

Member

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!

Member

cebe commented Jan 28, 2014

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

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 30, 2014

Member

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

Member

cebe commented Jan 30, 2014

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

This comment has been minimized.

Show comment
Hide comment
@samdark

samdark Jan 30, 2014

Member

It seems it doesn't display images.

Member

samdark commented Jan 30, 2014

It seems it doesn't display images.

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 30, 2014

Member

Can you show an example link?

Member

cebe commented Jan 30, 2014

Can you show an example link?

cebe added a commit that referenced this issue Jan 30, 2014

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Jan 30, 2014

Member

fixed. should be up to date in 15min

Member

cebe commented Jan 30, 2014

fixed. should be up to date in 15min

@cebe cebe added the ext:apidoc label Feb 24, 2014

cebe added a commit that referenced this issue Mar 7, 2014

@cebe

This comment has been minimized.

Show comment
Hide comment
@cebe

cebe Mar 7, 2014

Member

API doc generator is done.

Member

cebe commented Mar 7, 2014

API doc generator is done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment