Re: New doxygen script
On 13/01/14 16:15, Aurélien Gâteau wrote: Thanks a lot! I think you should merge your work in already. Once your script can generate a proper index.html page we can ask Allen to set up api.kde.org to use it for frameworks doc. I'm mostly waiting on the review requests I have outstanding - in particular, there's some stuff that should be moved to kdoctools, and I'd like to do that first. Oh, don't forget to document the way it works in the README.md :) I've documented how to use it in the README.md. How it works probably belongs in comments at the top of the scripts. The main KDE website is actually expected to be refreshed at some point to use the same appearance as bugs.kde.org or forum.kde.org, so we might want to skip the current kde.org look. Furthermore I don't think the current image background is very adapted for API documentation. Yeah, I also couldn't find a good place for the api search box. We can re-visit the look later. I am not very fond of two-level menus to be honest. I find a sidebar easier to use. At one point I got http://api.kde.org/frameworks/kdelibs-apidocs/ sidebar to look like this: * Tier 1 - kconfig - kcoreaddons - ... * Tier 2 - kauth - ki18n - ... Already done :-) Alex ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: New doxygen script
Le vendredi 10 janvier 2014 03:30:03 Alex Merry a écrit : Hey Aurélien, I wrote a new script to generate apidocs. It's in Python rather than shell script (because (a) yay for proper programming languages and (b) cross-platformness). If you run it on a framework like KCoreAddons, you'll get actual bona fide apidocs (unlike if you try to run doxygen.sh on it). It even pulls in README.md as the main page text. It can be found in kde:clones/kapidox/alexmerry/kapidox on the frameworks branch. Nice! I was thinking about porting the doxygen.sh script to Python as well, to help with maintainability and so that we can later use string.Template or even Jinja to handle HTML generation, but you beat me to it :) I never got the classpicker to show up, that's already a nice addition. As I understand it, it still lacks the ability to bundle documentations for multiple frameworks together right? Do you think it is missing anything else? One thing: you want to apply this patch: diff --git a/src/kgenapidox.py b/src/kgenapidox.py index 45e9cab..220cae1 100755 --- a/src/kgenapidox.py +++ b/src/kgenapidox.py @@ -239,7 +239,7 @@ def main(): srcdir = os.path.abspath(os.path.realpath(args.moduledir)) # Basic project info -modulename = os.path.basename(args.moduledir) +modulename = os.path.basename(srcdir) outputdir = modulename + '-apidocs' readme_file = os.path.join(srcdir, 'README.md') if os.path.isfile(readme_file): First time I tried the script with kgenapidox.py . and was surprised not to find any new doc dir: doc had been generated in .-apidocs :) One thing to take into account is KDE4 documentation. This is a question for Allen, I guess: is it possible to have api.kde.org uses the different apidox scripts for different sets of documentations so that we can use kde:kdelibs for KDE4 documentation and kde:kapidox for KF5 documentation? Aurélien ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: New doxygen script
On Fri, Jan 10, 2014 at 4:30 AM, Alex Merry k...@randomguy3.me.uk wrote: Hey Aurélien, I wrote a new script to generate apidocs. It's in Python rather than shell script (because (a) yay for proper programming languages and (b) cross-platformness). If you run it on a framework like KCoreAddons, you'll get actual bona fide apidocs (unlike if you try to run doxygen.sh on it). It even pulls in README.md as the main page text. It can be found in kde:clones/kapidox/alexmerry/kapidox on the frameworks branch. Alex ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel Nice initiative! Looking forward to understanding API documentation generation. :) Aleix ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: New doxygen script
On Friday, January 10, 2014 04:42:59 PM Aurélien Gâteau wrote: Le vendredi 10 janvier 2014 03:30:03 Alex Merry a écrit : Hey Aurélien, I wrote a new script to generate apidocs. It's in Python rather than shell script (because (a) yay for proper programming languages and (b) cross-platformness). If you run it on a framework like KCoreAddons, you'll get actual bona fide apidocs (unlike if you try to run doxygen.sh on it). It even pulls in README.md as the main page text. It can be found in kde:clones/kapidox/alexmerry/kapidox on the frameworks branch. Nice! I was thinking about porting the doxygen.sh script to Python as well, to help with maintainability and so that we can later use string.Template or even Jinja to handle HTML generation, but you beat me to it :) I never got the classpicker to show up, that's already a nice addition. As I understand it, it still lacks the ability to bundle documentations for multiple frameworks together right? Do you think it is missing anything else? One thing: you want to apply this patch: diff --git a/src/kgenapidox.py b/src/kgenapidox.py index 45e9cab..220cae1 100755 --- a/src/kgenapidox.py +++ b/src/kgenapidox.py @@ -239,7 +239,7 @@ def main(): srcdir = os.path.abspath(os.path.realpath(args.moduledir)) # Basic project info -modulename = os.path.basename(args.moduledir) +modulename = os.path.basename(srcdir) outputdir = modulename + '-apidocs' readme_file = os.path.join(srcdir, 'README.md') if os.path.isfile(readme_file): First time I tried the script with kgenapidox.py . and was surprised not to find any new doc dir: doc had been generated in .-apidocs :) One thing to take into account is KDE4 documentation. This is a question for Allen, I guess: is it possible to have api.kde.org uses the different apidox scripts for different sets of documentations so that we can use kde:kdelibs for KDE4 documentation and kde:kapidox for KF5 documentation? Yes, we should be able to run this new generation script for KF5 dox only. Give me the command line you want to execute and I should be able to take it from there. -Allen ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: New doxygen script
On 10/01/14 15:42, Aurélien Gâteau wrote: Le vendredi 10 janvier 2014 03:30:03 Alex Merry a écrit : Hey Aurélien, I wrote a new script to generate apidocs. It's in Python rather than shell script (because (a) yay for proper programming languages and (b) cross-platformness). If you run it on a framework like KCoreAddons, you'll get actual bona fide apidocs (unlike if you try to run doxygen.sh on it). It even pulls in README.md as the main page text. It can be found in kde:clones/kapidox/alexmerry/kapidox on the frameworks branch. Nice! I was thinking about porting the doxygen.sh script to Python as well, to help with maintainability and so that we can later use string.Template or even Jinja to handle HTML generation, but you beat me to it :) Proper templating would be good; currently the substitution is a bit hackish. New version has various improvements, and -- more importantly -- a kgenframeworksapidox script. Just point it at whatever folder has all your frameworks checkouts. It doesn't yet generate a main index.html, but it does do the global menu. It's also a bit inefficient about building - it does tier1, then tier2 (so they can reference tier1 docs), then tier3 twice (for interdependencies) then tier4 twice. Takes 20 minutes total on my machine. Alex ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
Re: New doxygen script
On 10/01/14 20:05, Alex Merry wrote: On 10/01/14 15:42, Aurélien Gâteau wrote: Le vendredi 10 janvier 2014 03:30:03 Alex Merry a écrit : Hey Aurélien, I wrote a new script to generate apidocs. It's in Python rather than shell script (because (a) yay for proper programming languages and (b) cross-platformness). If you run it on a framework like KCoreAddons, you'll get actual bona fide apidocs (unlike if you try to run doxygen.sh on it). It even pulls in README.md as the main page text. It can be found in kde:clones/kapidox/alexmerry/kapidox on the frameworks branch. Nice! I was thinking about porting the doxygen.sh script to Python as well, to help with maintainability and so that we can later use string.Template or even Jinja to handle HTML generation, but you beat me to it :) Proper templating would be good; currently the substitution is a bit hackish. Now with mustache-based templating (http://mustache.github.io/)! You might need to do `pip pystache` to get it to run. There's also an optional dependency on the Python yaml module (I haven't tested it without that module, though). The lookinggood branch is themed to match the main KDE website. I left it on a separate branch in case we decide that theme isn't clear enough (there's no sidebar, for example - all the menus are at the top). Alex ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
New doxygen script
Hey Aurélien, I wrote a new script to generate apidocs. It's in Python rather than shell script (because (a) yay for proper programming languages and (b) cross-platformness). If you run it on a framework like KCoreAddons, you'll get actual bona fide apidocs (unlike if you try to run doxygen.sh on it). It even pulls in README.md as the main page text. It can be found in kde:clones/kapidox/alexmerry/kapidox on the frameworks branch. Alex ___ Kde-frameworks-devel mailing list Kde-frameworks-devel@kde.org https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
