What about putting the phpdoc up in the git repository so one could watch it via github?
I guess the api is being generated by some process already, so it wouldn’t be that hard to put the generated html alongside the git repository on github
That would solve the hosting issue.
How would you solve the others?
I guess the CI stuff could only be fixed by investing some work and maybe using a different generator. I do not know how the API is generated, because I do not know the current generator.
Question is, if it would be of any benefit to invest the time to bring it into line with the CI.
As I am seeing here, nobody wants this anymore, but I wanted to throw that suggestion into the ring, because it came to my mind when reading the topic.
Initially I thought that github would provide an API tree of the source out of the box and would make the current solution obsolete anyway, but I must just have imagined this feature be a thing I guess.
From my point of view, the current solution could be removed anyway, because I do not use it anymore. I am linking to the github source if I want to reference some class or code.
I admit I’ve not used it; I agree in closing it if you can gather the same or better information with other tools.
Well, I use it rather often, but it would be no deal to look directly into the code instead. And yes, design not following the CI sucks a little bit. Looks like doxygen default template …
But I want to tell:
- Doxygen itself states, that it is not only “for C++”, but for generating a documentation from source-code comments. IMHO it is still defacto standard for doing such a task. (despite the fact, that it is not done that often anymore …)
- It is not a big deal to adjust the template. Although I must admit, I did that last time back in 2k or so …
- The biggest thing about is: the one who generates that docs, uses a doxygen version from early 2014, also for the v8. There are several minor releases out with a whole bunch load of bugfixes and enhancements, the latest version is from Dec 2017 … so some of the problems are maybe already solved upstream (IDE related comments, rendering issues, but I did not have a deeper look at that …)
- Everyone interested could build his own doxy-documentation. You just need the TYPO3 core and doxygen, which is an opensource tool under GPL v2. If you don’t have special needs for look-and-feel or so, it is a nobrainer
I would throw phpDocumentor in the ring. It’s available through composer and should do a better job, because it’s a generator explicitly designed for PHP applications.
I agree with using phpdocumentor3, however ONLY if there is a person (or multiple) stepping up right now, doing that job on a regular / maintenance basis.
Other than that - if there is no maintainer, we should shut the current service down.
I tried to setup a little test with phpDocumentor, but I can’t get it to work properly. Also tried apiGen, but this isn’t really a great alternative, since it complains about non existent Classes and the whole Project has to be setup. So apiGen would generate a huge API with lots of classes of foreign packages, which I think isn’t great at all.
So… since phpDocumentor seems not to get enough love to be a viable option, I guess we could scratch that option and just turn off api.typo3.org without an alternative then.
However, it shouldn’t be a big deal since one can link sources and classes on github if needed.
I would just recomment to communicate some solution to the users of the service, whether it will be github or something else.
I still use the API web version regularly. And I use it alongside my IDEs integration. Because browsing the source code and autocompletion is different from a rendered web version. While the first is probably all what a developer needs in everyday work the latter in my opinion is a good way to gain insight into functionality and features. I for example used the web version to get familiar with the File Abstraction Layer. I believe that a documentation created und updated by editors will always be incomplete and out-dated to some extent. Its purpose should be to document the important stuff, the common ways to do things and best practices. For those who need to know more there should be an automatically generated and therefore up-to date version of the API.
Furthermore I believe that a public web version of the API is part of the presentation of TYPO3 as an Open Source Enterprise CMS. It may not be the most important part but it shows that TYPO3 is not only a CMS but also a framework that allows and supports customization in an extensive and professional way. I wonder why Drupal and Symfony have public web version of their API available.
That being said I wouldn’t be too sad if the web version would be shut down. If there are issues and no-one takes care of it it’s probably better to shut it down. Although there a good reasons to keep and improve it.
I will test phpdocumentor in the next week in combination with sphinx, so maybe there is an option to integrate the phpdocumentor / doxygen output into docs.typo3.org
Since I probably kind of triggered this discussion with the last api issue ((https://forge.typo3.org/issues/83689) I thought I might comment as well.
There are several sides to this as has already been mentioned:
- Is the api.typo3.org necessary or is browsing the api sufficiently or better done with other tools (mostly IDE)?
- Does it provide any additional advantage?
Personally, I’ve used api.typo3.org several times, I like browsing through it, reading code and jumping back and forth between code and structure. You can probably do that more or less just as well with an IDE, but it’s kind of a convenience thing. Not everyone works 100% with TYPO3 and has everything available to set it up. People who evaluate, might want to peek in the code first. Sometimes you just want to browse a specific version but not download it. Sometimes you don’t have your laptop with you or your phpstorm license key etc. etc. I’d find it annoying if Drupal has it and TYPO3 does not.
That being said: It is also a question of resources and priorities. If the resources are simply not there and the priorities of api.typo3.org is quite low, I think you should put the effort into other things. If it is not possible to fix the current problems (e.g. estimated ~390 public functions simply missing), it should be shut down.
One other thing: the people who replied here are mostly core team. Those are the people who find it least important. If and when you shut it down, you will find, there are suddenly other people who do miss it. For those, as has already been mentioned:
Redirect in a non-obtrusive way and communicate the other resources (github, using IDE).
P.S. For the issue I reported, I pretty much tested this extensively, however only locally using standard doxygen configuration so I am not sure my results are identical, but anyway I could reproduce the missing public functions and fix it with 1 line of change in the doxygen configuration (but we all know it is usually not that easy and new problems might pop up).
This topic was automatically closed after 14 days. New replies are no longer allowed.