Doxygen generate docset
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:
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.
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.
#1 Updated by Fabien Udriot over 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
Download whole API
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 over 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 <firstname.lastname@example.org>
Perhaps his documentation and links about generating Docsets will help you: http://kapeli.com/docsets
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.
#5 Updated by Daniel Siepmann over 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.
#7 Updated by Daniel Siepmann over 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.
I'll look into it and will most likely include Typo3 with a future version :)
#8 Updated by Fabien Udriot over 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.
#10 Updated by Daniel Siepmann over 5 years ago
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 over 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.
#14 Updated by Christoph Gross over 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