Bug #37427

Doxygen generate docset

Added by Daniel Siepmann about 5 years ago. Updated almost 2 years ago.

Status:
Resolved
Priority:
Should have
Assignee:
Category:
-
Start date:
2012-05-23
Due date:
% Done:

0%

Estimated time:
0.50 h
Tags:
doxygen

Description

Hey all,

I found a nice tool for Mac OS X named Dash. http://kapeli.com/dash/
This tool can fetch docsets from an url and provide them offline for developers.
I tried to use this with the api.typo3.org documentations generated with doxygen.
But this doesn't work. After contacting the developer I got the following answer:

Hi Daniel,

I'm afraid it's not that simple.

Information on generating a docset can be found at http://kapeli.com/docsets

The section you would be interested in is the Doxygen one (as far as I can tell typo3 already uses doxygen).

In short, you need to find out how typo3 generates the documentation and edit their doxygen .doxy file (it's a config file) and set:

GENERATE_DOCSET = YES

After that, you run doxygen and open Terminal, go to the html-generated documentation folder and run "make".

Your end result needs to be a file of the format .docset, which Dash can open by just double clicking on it.

Regards,
Bogdan

I think the only one we have to do, to make the TYPO3-API available for this program is to set the option GENERATE_DOCSET to YES.
Is this possible? I think that's very easy to change.

Screen_Shot_2012-05-24_at_10.07.48_AM.png View - Result for a sample search inside Dash after adding TYPO3 docset (207 KB) Daniel Siepmann, 2012-05-24 10:09

Associated revisions

Revision 1f8a7395 (diff)
Added by Fabien Udriot about 5 years ago

[FEATURE] Add support for Docset documentation, references #37427

Change-Id: Ib91c3597f1ff6c15d0eeb4bea2ffbfba79600cab

History

#1 Updated by Fabien Udriot about 5 years ago

  • Status changed from New to Needs Feedback
  • Assignee set to Fabien Udriot

I have changed the setting GENERATE_DOCSET = YES and have re-generated API for master TYPO3v4

Online resource:
http://api.typo3.org/typo3v4/master/html/

Download whole API
http://api.typo3.org/archives/typo3_src-master.zip

Please, let me know what result you get from this tool whether there is anything to share back to the community.

#2 Updated by Daniel Siepmann about 5 years ago

I tried it, but it looks like there is still no .docset-File, even in the download.
I'm not familiar with either how the Program works, or how Doxygen works.
Perhaps you can contact Bogdan (the developer of the app) directly? He's really friendly and answers very fast.
Perhaps he'll add the documentation, once it works, to his app.
His email is: Kapeli <>

Perhaps his documentation and links about generating Docsets will help you: http://kapeli.com/docsets

EDIT:

After trying it on my own I noticed that we have to run "_make_" inside the html-folder to generate the .docset file.
If we can integrate this command into the build process we can link to this file from the programm.
Using the manually generated .docset on my machine works very well.

For automatic download and update the programm still needs an xml-file. I don't know how to generate this file or anything about the content.

Running the make cmd on my pc took some minutes.

#3 Updated by Daniel Siepmann about 5 years ago

Here is an screenshot of the result inside Dash

#4 Updated by Philipp Gampe about 5 years ago

So it works now or not?

#5 Updated by Daniel Siepmann about 5 years ago

It works if you download the complete html-Folder and run "make". This will generate the .docset file.

It will be awesome if we can generate this docset file while generating the API. Then the user only has to download this file and add it to the program.
The best solution will be the xml-file needed by the program to provide the user with an automatic download.

For me the current solution is enough. But perhaps we can add the additional features in the feature.

Thanks for the fast answers and help.

#6 Updated by Fabien Udriot about 5 years ago

After trying it on my own I noticed that we have to run "_make_" inside the html-folder to generate the .docset file.

Ok, I see the point. Will try to investigate in that direction.

#7 Updated by Daniel Siepmann about 5 years ago

Bogdan told me that we can create the xml file as described on the bottom of his help page: http://kapeli.com/docsets/#feeds (see section Host your own Dash documentation feed)
This is a small xml-file containing the url to the docset file.

With this little improvement we are able to deliver the current state to the program and Bogdan will add the TYPO3 to his program.

Hi Daniel,

I'll look into it and will most likely include Typo3 with a future version :)

[...]

Regards,
Bogdan

#8 Updated by Fabien Udriot about 5 years ago

Ok, so there are some progress here.

  • Added a docset file in the archive folder for downloading. Hope it is right for you.
  • Updated the Doxygen configuration file with more appropriate settings.
GENERATE_DOCSET        = YES
DOCSET_FEEDNAME        = "TYPO3v4 API" 
DOCSET_BUNDLE_ID       = org.typo3.Typo3
DOCSET_PUBLISHER_ID    = org.typo3.Publisher

Notice this Docset file is not automatically built (read updated) because it relies on command docsetutil which is a Developer Mac tool. Since our server is running a Debian OS, it is not possible to include the make into the chain. It means the Docset version should be generated for each major release of TYPO3. However, a TYPO3 developer could anyway run on its machine the make command to have the latest.

  • A patch have been pushed and merged to prepare the ground http://review.typo3.org/11646
  • the API page of typo3.org has been updated with a mention to Docset
  • Last but not least, I have added a XML file for streaming purposes with Dash. Author has been informed.

Re-open the bug if something missing / wrong.

And feel free to spread the word about the availability of TYPO3 API in Docset format.

#9 Updated by Fabien Udriot about 5 years ago

  • Status changed from Needs Feedback to Resolved

#10 Updated by Daniel Siepmann about 5 years ago

When will this updates be available?
Currently the links downloading and XML file are dead (404 Not Found).

The downloading-Link has just a uppercase problem: http://api.typo3.org/archives/Typo3.docset.tgz has to be http://api.typo3.org/archives/TYPO3.docset.tgz
But I don't get a working link for http://api.typo3.org/feeds/Typo3.xml .

The .docset-File works very well. Big thanks.

#11 Updated by Fabien Udriot about 5 years ago

Right! I did some more work without putting the info here. I knew you were reporting that ;)

To say that the next version of Dash will have TYPO3 Docset built in - as communicated by its author :)

As a result:

  • XML Feed has been deleted which has become useless.
  • Docset has been moved to the archive as you noticed.

#12 Updated by Daniel Siepmann about 5 years ago

Well that's nice.
Thank you for the work.

#13 Updated by Christoph Gross almost 2 years ago

I just tried to find Typo3 in Dash but it's not there. Is the .docset file still around anymore? The link to the archive is dead.

#14 Updated by Christoph Gross almost 2 years ago

UPDATE: Apparently there is a Typo3 docset in Dash -.- However not all is wasted since the script can be used for basically every git repo on git.typo3.org. I will make a new pull-request for Flow...

I spent some time this weekend to write a script which generates docsets for all major Typo3 versions (and also Typo3 FLOW): https://github.com/cgrossde/Typo3Docsets

I also made a pull-request to get these docsets added to Dash again here: https://github.com/Kapeli/Dash-User-Contributions/pull/529

Until they are merged, they can be downloaded here: https://github.com/cgrossde/Typo3Docsets/releases/tag/0.1.0

PS: Does anyone know if the doxygen excludes for Typo3 6.x in the ApiTypo3Org still make sense or if they should be applied to 4.x also? https://git.typo3.org/Documentation/ApiTypo3Org.git/blob/HEAD:/Classes/Doxygen.php#l91

Also available in: Atom PDF