Skip to content
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
Closed

Enhance api doc generator #1797

cebe opened this issue Jan 6, 2014 · 36 comments
Assignees
Milestone

Comments

@cebe
Copy link
Member

@cebe 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
Copy link
Member

@qiangxue qiangxue commented Jan 6, 2014

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

@qiangxue
Copy link
Member

@qiangxue qiangxue commented Jan 6, 2014

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

@cebe
Copy link
Member Author

@cebe 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
Copy link
Member

@qiangxue 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
Copy link
Member

@samdark samdark commented Jan 6, 2014

chm is frequently requested.

@samdark
Copy link
Member

@samdark samdark commented Jan 6, 2014

Structure is perfect in 1.1 API docs.

@qiangxue
Copy link
Member

@qiangxue qiangxue commented Jan 6, 2014

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

@cebe
Copy link
Member Author

@cebe 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
Copy link
Member

@samdark samdark commented Jan 6, 2014

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

@cebe offline.

@cebe
Copy link
Member Author

@cebe cebe commented Jan 6, 2014

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

@samdark
Copy link
Member

@samdark 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
Copy link
Member

@qiangxue 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
Copy link
Member

@samdark samdark commented Jan 6, 2014

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

@qiangxue
Copy link
Member

@qiangxue qiangxue commented Jan 6, 2014

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

@samdark
Copy link
Member

@samdark samdark commented Jan 6, 2014

Should be OK then.

@cebe
Copy link
Member Author

@cebe 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
Copy link
Contributor

@dilip-vishwa 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
Copy link
Member Author

@cebe 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
Copy link
Member

@samdark samdark commented Jan 24, 2014

Looks great!

@qiangxue
Copy link
Member

@qiangxue 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
Copy link
Contributor

@lucianobaraglia 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
Copy link
Member

@qiangxue 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
Copy link
Member

@samdark samdark commented Jan 24, 2014

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

@cebe
Copy link
Member Author

@cebe 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
Copy link
Member

@qiangxue 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
Copy link
Member

@qiangxue 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
Copy link
Contributor

@marsuboss marsuboss commented Jan 28, 2014

Is it possible to sort methods and properties ?

@samdark
Copy link
Member

@samdark samdark commented Jan 28, 2014

Absolutely possible and I think it should be done.

@cebe
Copy link
Member Author

@cebe 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
Copy link
Member Author

@cebe 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
Copy link
Member Author

@cebe 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
Copy link
Member

@samdark samdark commented Jan 30, 2014

It seems it doesn't display images.

@cebe
Copy link
Member Author

@cebe cebe commented Jan 30, 2014

Can you show an example link?

cebe added a commit that referenced this issue Jan 30, 2014
issue #1797
@cebe
Copy link
Member Author

@cebe 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
issue #1797
@cebe
Copy link
Member Author

@cebe 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
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants
You can’t perform that action at this time.