Re: [Development] Towards a Qt 5 beta: Documentation
On Thu, Apr 12, 2012 at 4:12 PM, wrote: > 4. The QDoc commands and functionality are not known well enough by > For issue 4 I would like to point people to > http://doc-snapshot.qt-project.org/qdoc/ this is the URL of the qdoc > manual. If everybody follows what is written there and reports bugs about > inconsistencies in the manual we should have a minimal influx of new qdoc > errors. Is it okay to to also report language and phrasing issues within the manual? I've started reading through it to help with (4) and spotted some of those that might make it confusing for the uninitiated / non native speakers to follow, possibly warranting bug report(s). -Sivan ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On 4/24/12 9:53 AM, "ext casper.vandonde...@nokia.com" wrote: >Hi, > >I just cut out the rest of the email for clarity. (great that you would >want to help) > >I just want to talk about the inherits and inherited by problem. >"Inherits" should always work, because you compile the Qt code that way >(you cannot subclass a class that doesn't exist yet). > >I just want to make clear that fixing the "Inherited by" problem without >building all documentation in one go is not that easy. >In theory it would be very easy: We would put the "inherited by" in a >unique HTML element, for example: . That way we can >open the file as a qdomdocument and replace that paragraph with a new >list. > >We have said that documentation will get installed to QT_INSTALL_DOCS, >which might be a folder which requires root write-access, in that case we >would need to ask for the sudo password while qdoc is running to be able >to re-write the "inherited by" list, which I think is also not feasible. The other problem as to why this is difficult is optional add-ons. How do you handle the case that someone adds another add-on. Do we want to show these as well then? I think the only way to solve this is to generate that list on the fly when asked for, ie. do a reverse search through all the installed documentation. the help module in creator could implement something like this. Cheers, Lars > > >Proposals for different approaches are always welcome of course. > > >Casper > >___ >Development mailing list >Development@qt-project.org >http://lists.qt-project.org/mailman/listinfo/development ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
Hi, I just cut out the rest of the email for clarity. (great that you would want to help) I just want to talk about the inherits and inherited by problem. "Inherits" should always work, because you compile the Qt code that way (you cannot subclass a class that doesn't exist yet). I just want to make clear that fixing the "Inherited by" problem without building all documentation in one go is not that easy. In theory it would be very easy: We would put the "inherited by" in a unique HTML element, for example: . That way we can open the file as a qdomdocument and replace that paragraph with a new list. We have said that documentation will get installed to QT_INSTALL_DOCS, which might be a folder which requires root write-access, in that case we would need to ask for the sudo password while qdoc is running to be able to re-write the "inherited by" list, which I think is also not feasible. Proposals for different approaches are always welcome of course. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On Thu, Apr 12, 2012 at 4:35 PM, André Somers wrote:
> I think that loosing all the cross links and all the inherited-by links
> that span modules is unaceptable. For instance, you would no longer be
> able to see relations between some major classes, like QObject ->
> QWidget. You'd only be able to see QWidget -> QObject. These kinds of
> links are not something that does not happen. The QObject docs are a
> good example of that, as they actually reference QWidget. Personally, I
> also regulary use the Inherited by list. I would hate to see that go.
>
My personal opinion is that when you are reading about QObject it is
good to know that QWidgets all inherit from it, as noted (in
http://qt-project.org/doc/qt-4.8/QObject.html) :
"All Qt widgets inherit QObject. The convenience function
isWidgetType() returns whether an object is actually a widget. It is
much faster than qobject_cast(obj) or
obj->inherits("QWidget")."
But is not mandatory. My feeling is that it is more suitable at the
Widget docs, as it is necessary for completeness of the discussion.
And has sufficient address in this statement which is the actual
content.
This would also make it less bloated, as when you open the page you
get this enormous list of those who inherit and you want to learn just
about QObject. My assumption also is that a new user might be
overwhelmed by that.
Thoughts?
-Sivan
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On Thu, Apr 12, 2012 at 4:12 PM, wrote: > TL;DR: We need to change the way Qt does documentation. A lot of things > will change and we need help from everybody. > This is granted, but as the whole Qt5 process looks, this will be for the good. > As mentioned by Lars: We should make sure the quality of the documentation > for Qt 5.0 is as high as possible. > The framework is amazing, I'm keen to help the effort to enable more and more people to experience it and exploit it for their needs. Docs are instrumental in that (as I mentioned before to anybody who would listen ;)). > To get and keep our documentation in shape for Qt 5.0 and beyond I think > we will need to tackle the following problems > .4. The QDoc commands and functionality are not known well enough by > people, which causes QDoc errors. I guess, beyond the fine manual (tm), we could provide cheat sheets (like mongodb[0] has) and tips blog posts such that this would quickly change. I also think it'd be good to have recent qt users to be part of the review/ approval process. I still odd at some of the docs I use, so I hereby volunteer. > 5. There is no real review process for documentation contributions. > There are two use cases here as I see it, to establish a review process based on actual use: 1. I want to do X , has Doc material Y enabled me to do so? 2. I want to learn how to use Qt-mobility (can't help it. I love this module) to its fullest - Is there 'The' tutorial that introduces me to the subject, and enables me to follow a real-world, working example in my interface of choice (e.g. QML or Qt/C++) ? Once we gather some interested parties off the community we can test-drive docs through 1 and 2 to make sure it is new b friendly. Again, I'm interested in that - is there a way I can subscribe to changes for that, be assigned as one of the reviewers for that through Gerrit ? > Modularizing the documentation is a process that will move a lot of files > around and make some things impossible. Inevitable, but for an extremely good cause. > The biggest consequence will be that we will have the same dependency > chain as when compiling the modules. > E.g. not allow circular dependencies in the documentation. Therefore there > can be no links from the QtGui documentation to any class in QtWidgets, My 0.02EU Cents: As I see it, QtGui should have been lean abstraction away from QtCore - should not have contained any Widget related stuff (this should be in either another widget stack or in the new Qt Quick components stack) so this makes a lot of sense to me, also from the API design view. > from QtWidgets to QtGui will work, since Widgets depends on Gui. > This will also automatically break "Inherited by:" between classes in > separate modules in the documentation. Perhaps there would be a way to make QDoc aware of that? by some new directive that would tell it where to look for the base? > I have written down a possible method for modularizing the documentation > at the end of this email. That should make the whole process more > transparent. > > Issue 3 just needs people to clean up the documentation, writing > guidelines to get this standard will be published on the Qt Project Wiki. > Please post here when this guideline is ready, thanks! > For issue 4 I would like to point people to > http://doc-snapshot.qt-project.org/qdoc/ this is the URL of the qdoc > manual. If everybody follows what is written there and reports bugs about > inconsistencies in the manual we should have a minimal influx of new qdoc > errors. Bookmarked. > There are problems in qdoc (like not understanding C++ templates/macros > and C++11 syntax for documenting QObject::connect), but we should not > start putting Doxygen documentation commands in QDoc when there is a QDoc > equivalent. > I am also aware that we still need to change a lot of "old" documentation, > like replacing all \gui commands with \uicontrol, which is quite a simple > search/replace. > These are QDoc commands I take it? /me goes to do some QDoc manual reading. > > Issue 5 needs thought and help from everybody. We will keep the normal > reviewing process for documentation and we cannot enforce all > documentation patches to be reviewed by native English speakers/technical > writers. But when documentation changes we should all pay special > attention to making it understandable to someone who is new to Qt. This > has always been the focus of the Qt documentation and I think we should > try to keep the same standard of documentation going forward. > I'm keen to see if I can send a call for help to the greater community, to see who's willing to take part in a doc review team we could form on Gerrit, also see my previous suggestion of the use cases for review. > > -- Modularized documentation proposal > - Individual modules have their documentation in > /src/[conveniencename]/doc. For example: "/src/corelib/doc". Documentation > .qdoc files will stay under "src" in that folder
Re: [Development] Towards a Qt 5 beta: Documentation
Hi, > >There are other tasks that seems to be missing. > >- What is documentation? Are we talking only about the API docs or also >about code examples, tutorials, demo videos? I don't want to talk about any of the non-API documentation for now, since that is also a mess that needs to be cleaned up. I think we should first try to get the key features for people that already use Qt in place and focus on content for new users later. >- Who are the contributors working specifically in the deliverables >described above, and who is the overall responsible? Now it feels that a >lot of responsibilities fall between the cracks. That was ok-ish for the >pre-alpha phase but now we need more organization. I am working on the cross-linking, Since I have not heard concrete other ideas I'll just implement the proposal and try to keep the current "magical" system working at the same time. Nobody is responsible in the end. The most responsibility I am willing to take is delivering a QCH package of the documentation when we build an SDK/give a documentation package to the DevNet people to publish. This means other people/companies will also have to step in. >- What are the deliverables for the beta release? Documentation wasn't a >showstopper for an alpha release but certain documentation criteria need >to be met for the beta. What are those criteria? The deliverables are a QCH package and getting the documentation on the DevNet. There are no concrete criteria, but I would like to enforce that we have a similar amount of qdoc errors in 5.0 compared to 4.8. 4.8 has around 50 qdoc errors. The monolithic 5.0 package currently has around 8000, I cannot say anything about modular 5.0 yet. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On 4/13/12 10:32 AM, "ext Oswald Buddenhagen"
wrote:
>On Fri, Apr 13, 2012 at 07:04:42AM +, ext
>casper.vandonde...@nokia.com wrote:
>> You are correct, that is what will happen, the same as the current
>>system.
>> The thing is that people have difficulty understanding where
>> QT_QML_QDOCCONF etc. come from currently.
>>
>> I can see a problem with this since for Qt QtCore is just called core,
>>and
>> I would not want to output the documentation to just /doc/core, but
>> /doc/qtcore, since there might be modules that do not start with Qt and
>> still use QDoc.
>>
>big deal.
>qdoc_deps =
>for(m, QT): qdoc_deps += $$lower($$eval(QT.$${m}.name))
>
>and all that should be centralized in qt_module_config.prf, where all
>the module creation magic happens. a lot more is already pending for the
>buildsystem branch.
>
>you should ask the buildsystem guys a bit more often in advance instead
>of complaining that they are complaining about your solutions. ;)
Ok, that will work for Qt C++ modules. If a user has a QML-only module we
still need to hard-code it in the .pri file then.
Casper
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On Fri, Apr 13, 2012 at 07:04:42AM +, ext casper.vandonde...@nokia.com
wrote:
> You are correct, that is what will happen, the same as the current system.
> The thing is that people have difficulty understanding where
> QT_QML_QDOCCONF etc. come from currently.
>
> I can see a problem with this since for Qt QtCore is just called core, and
> I would not want to output the documentation to just /doc/core, but
> /doc/qtcore, since there might be modules that do not start with Qt and
> still use QDoc.
>
big deal.
qdoc_deps =
for(m, QT): qdoc_deps += $$lower($$eval(QT.$${m}.name))
and all that should be centralized in qt_module_config.prf, where all
the module creation magic happens. a lot more is already pending for the
buildsystem branch.
you should ask the buildsystem guys a bit more often in advance instead
of complaining that they are complaining about your solutions. ;)
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On 4/13/12 7:34 AM, "Lincoln Ramsay" wrote: >On 04/13/2012 03:19 PM, Vandonderen Casper (Nokia-MP/Oslo) wrote: >> But I would be grateful if you would make a plan on how to turn qdoc >> into a mini-qmake so that qdoc can parse the .pro/sync.profile, so >> that we don't need the depends. Because that would probably also mean >> that you have to run "qdoc [module.pro] [module.qdocconf]", or do you >> see that differently? > >Doesn't qmake run over doc.pri to generate a Makefile rule "make docs" >that you run? Or are we moving away from "make docs" and towards running >qdoc explicitly? You are correct, that is what will happen, the same as the current system. The thing is that people have difficulty understanding where QT_QML_QDOCCONF etc. come from currently. I can see a problem with this since for Qt QtCore is just called core, and I would not want to output the documentation to just /doc/core, but /doc/qtcore, since there might be modules that do not start with Qt and still use QDoc. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On 04/13/2012 03:19 PM, Vandonderen Casper (Nokia-MP/Oslo) wrote: > But I would be grateful if you would make a plan on how to turn qdoc > into a mini-qmake so that qdoc can parse the .pro/sync.profile, so > that we don't need the depends. Because that would probably also mean > that you have to run "qdoc [module.pro] [module.qdocconf]", or do you > see that differently? Doesn't qmake run over doc.pri to generate a Makefile rule "make docs" that you run? Or are we moving away from "make docs" and towards running qdoc explicitly? -- Lincoln Ramsay - Senior Software Engineer Qt Development Frameworks, Nokia - http://qt.nokia.com/ ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
Hi, > We had cross-module links in both directions. We achieved this by > running qdoc twice per module. Once to get the .index (used for > resolving links) and again to build with the other modules' .index > files. The only way to avoid doing things twice would be to have more > intermediate steps in the doc building process (ie. generate indexes, > etc for everything then bring those together into a final product and > resolve all the links then). I have been thinking about this problem for some time, and while it is technically possible from a qdoc side to implement the whole system like this: I don't see the CI system handling anything like this, what we could do is have a previous run of all the index files somewhere for the CI system to find, but that would theoretically open up the possibilty that I remove a documentation \class from QtCore, but it will still be found in the index. The missing file will only show up when you run qhelpgenerator to generate the QCH files. And I haven't even talked about the qhelpgenerator/QCH process yet, because that thing is still in qttools and can therefore not be run in the CI for qtbase. >> - For cross-linking we need to do a few things (None of this is >> implemented yet): >> 1. We need to add a "depends" qdocconf variable, where you list the >> modules you depend on. > > Why?! We already have our dependencies stated in the sync.profile and > module .pro files. Duplicating this information just causes a > maintenance burden. Allowing explicit dependencies on docs (where there > is no dependency between modules) may make sense but dependencies > derived from the build should be extracted from the build. Adding this information extra in the qdocconf file will not be that harmful I think because we don't change the dependency tree that often anymore. But I would be grateful if you would make a plan on how to turn qdoc into a mini-qmake so that qdoc can parse the .pro/sync.profile, so that we don't need the depends. Because that would probably also mean that you have to run "qdoc [module.pro] [module.qdocconf]", or do you see that differently? Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
Hi. In general I applaud this effort. I'm going to talk about some of the doc things Qtopia had. Most of this came from our (infamous for being unmaintainable) mkdocs script. Given the reputation that script had I'm not about to suggest we implement things similarly in Qt but perhaps the ideas are worth something. In an effort to stop people from ignoring doc errors (by not building docs), we developed a system that automatically built the docs for a given directory when running make there. It was very quick (compared to building all docs) though its output wasn't very useful but we only cared about the errors anyway. QtSensors (and I guess other Qt modules) already have a similar-ish system in place where they can build their docs separately from the rest of Qt. Again, the result isn't very useful compared to a full doc build but it's very fast and great for reviewing doc changes as they're happening (though it's not automatic). We had cross-module links in both directions. We achieved this by running qdoc twice per module. Once to get the .index (used for resolving links) and again to build with the other modules' .index files. The only way to avoid doing things twice would be to have more intermediate steps in the doc building process (ie. generate indexes, etc for everything then bring those together into a final product and resolve all the links then). > - For cross-linking we need to do a few things (None of this is > implemented yet): > 1. We need to add a "depends" qdocconf variable, where you list the > modules you depend on. Why?! We already have our dependencies stated in the sync.profile and module .pro files. Duplicating this information just causes a maintenance burden. Allowing explicit dependencies on docs (where there is no dependency between modules) may make sense but dependencies derived from the build should be extracted from the build. -- Lincoln Ramsay - Senior Software Engineer Qt Development Frameworks, Nokia - http://qt.nokia.com/ ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On 4/12/12 4:09 PM, "ext Olivier Goffart" wrote: >On Thursday 12 April 2012 15:35:45 André Somers wrote: >> Op 12-4-2012 15:12, casper.vandonde...@nokia.com schreef: >> > Modularizing the documentation is a process that will move a lot of >>files >> > around and make some things impossible. >> > The biggest consequence will be that we will have the same dependency >> > chain as when compiling the modules. >> > E.g. not allow circular dependencies in the documentation. Therefore >>there >> > can be no links from the QtGui documentation to any class in >>QtWidgets, >> > from QtWidgets to QtGui will work, since Widgets depends on Gui. >> > This will also automatically break "Inherited by:" between classes in >> > separate modules in the documentation. >> >> While I understand the reasoning, I am not sure the limitations above >> are acceptable. At least, if I understand you correctly. >> >> I think that loosing all the cross links and all the inherited-by links >> that span modules is unaceptable. For instance, you would no longer be >> able to see relations between some major classes, like QObject -> >> QWidget. You'd only be able to see QWidget -> QObject. These kinds of >> links are not something that does not happen. The QObject docs are a >> good example of that, as they actually reference QWidget. Personally, I >> also regulary use the Inherited by list. I would hate to see that go. >> >> I don't have a solution ready though. >> > > >I also don't like it. What is the benefit of doing that? what went wrong >with >make docs? > >Also, you seem to use the "Module" terminology to refer to library >(QtCore, >QtGui, ...) within qtbase. But some other people may refer to "Module" >for >the repositoies (qtbase, qtdeclarative, qtscript, ...). >This is a bit confusing, please clarify. I think we've been trying to use this consistently since quite some time. But to remind everybody: * repositories is the stuff you store your source code in. They are not visible to users of Qt, only to use that develop Qt. * modules is the structure that is visible to the users of Qt. It's shared libraries for C++ (and a 'QT += foo' statement in the pro file) and QML modules (ie. a import statement in a QML file). Let's stick to that terminology. Cheers, Lars ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On 4/12/12 7:27 PM, "ext casper.vandonde...@nokia.com" wrote: >>> There are 2 main problems with the current system: >>> 1. Nobody was running "make docs" on their local machines (and >>>verifying the >>> output). There are qdoc errors that were put in by developers last >>> December. Having the documentation modularized will at some point >>> (hopefully soon) allow us to put documentation generation in the CI >>>system. >>> This would allow us to catch patches causing qdoc errors. >>> 2. It was/is completely unclear how the system works, there hasn't >>>been any >>> QML documentation at http://doc-snapshot.qt-project.org/5.0/ for >>>multiple >>> weeks now (I believe 4, maybe more). >> >> But none of those problem will be fixed by modularizing the docs by >>libraries. >> Or am i missing something? >> >> >> (putting make docs in the CI is a good idea) > >The CI system the documentation will be built per repository, that is >true, but there might be users who only want to build a specific set of >libraries with documentation and the extra step of granularity will not >make a difference (in my opinion), since the only difference would be a >few extra qdocconf files and make targets. In addition, this is a good practice. We might later on split out certain parts from the qtbase repo, and I want this to be possible. The second side is that users should *not* be exposed to our repo structure. If we have uplinks one place people expect them to work everywhere. But that's completely incompatible with a modular structure, where one can add and remove libraries from the SDK (something we need to aim for in the longer term). I can't see a way how you could possibly have a complete list of classes inheriting e.g. QObject in such a modular world. And I don't think it's desirable neither. > >I also think that adding the documentation build closer to the source >build (we could add the "make corelib-docs" target to corelib.pro) will >make the whole system more transparent and (psychologically) easier to >use. Or simple 'cd src/corelib; make docs' ;-) Cheers, Lars ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On 04/12/2012 06:12 AM, ext casper.vandonde...@nokia.com wrote: > To get and keep our documentation in shape for Qt 5.0 and beyond I think > we will need to tackle the following problems: > 1. The documentation is not modularized. > 2. The documentation build system is hard to explain to people. > (consequence of 1) > 3. The different Qt modules have a completely different style of > documenting. > 4. The QDoc commands and functionality are not known well enough by > people, which causes QDoc errors. > 5. There is no real review process for documentation contributions. There are other tasks that seems to be missing. - What is documentation? Are we talking only about the API docs or also about code examples, tutorials, demo videos? - Who are the contributors working specifically in the deliverables described above, and who is the overall responsible? Now it feels that a lot of responsibilities fall between the cracks. That was ok-ish for the pre-alpha phase but now we need more organization. - What are the deliverables for the beta release? Documentation wasn't a showstopper for an alpha release but certain documentation criteria need to be met for the beta. What are those criteria? -- Quim ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
>> There are 2 main problems with the current system: >> 1. Nobody was running "make docs" on their local machines (and verifying the >> output). There are qdoc errors that were put in by developers last >> December. Having the documentation modularized will at some point >> (hopefully soon) allow us to put documentation generation in the CI system. >> This would allow us to catch patches causing qdoc errors. >> 2. It was/is completely unclear how the system works, there hasn't been any >> QML documentation at http://doc-snapshot.qt-project.org/5.0/ for multiple >> weeks now (I believe 4, maybe more). > > But none of those problem will be fixed by modularizing the docs by libraries. > Or am i missing something? > > > (putting make docs in the CI is a good idea) The CI system the documentation will be built per repository, that is true, but there might be users who only want to build a specific set of libraries with documentation and the extra step of granularity will not make a difference (in my opinion), since the only difference would be a few extra qdocconf files and make targets. I also think that adding the documentation build closer to the source build (we could add the "make corelib-docs" target to corelib.pro) will make the whole system more transparent and (psychologically) easier to use. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On Thursday 12 April 2012 16:30:39 casper.vandonde...@nokia.com wrote: > >> While I understand the reasoning, I am not sure the limitations above > >> are acceptable. At least, if I understand you correctly. > >> > >> I think that loosing all the cross links and all the inherited-by links > >> that span modules is unaceptable. For instance, you would no longer be > >> able to see relations between some major classes, like QObject -> > >> QWidget. You'd only be able to see QWidget -> QObject. These kinds of > >> links are not something that does not happen. The QObject docs are a > >> good example of that, as they actually reference QWidget. Personally, I > >> also regulary use the Inherited by list. I would hate to see that go. > >> > >> I don't have a solution ready though. > > > > I also don't like it. What is the benefit of doing that? what went wrong > > with make docs? > > There are 2 main problems with the current system: > 1. Nobody was running "make docs" on their local machines (and verifying the > output). There are qdoc errors that were put in by developers last > December. Having the documentation modularized will at some point > (hopefully soon) allow us to put documentation generation in the CI system. > This would allow us to catch patches causing qdoc errors. > 2. It was/is completely unclear how the system works, there hasn't been any > QML documentation at http://doc-snapshot.qt-project.org/5.0/ for multiple > weeks now (I believe 4, maybe more). But none of those problem will be fixed by modularizing the docs by libraries. Or am i missing something? (putting make docs in the CI is a good idea) ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
>> While I understand the reasoning, I am not sure the limitations above >> are acceptable. At least, if I understand you correctly. >> >> I think that loosing all the cross links and all the inherited-by links >> that span modules is unaceptable. For instance, you would no longer be >> able to see relations between some major classes, like QObject -> >> QWidget. You'd only be able to see QWidget -> QObject. These kinds of >> links are not something that does not happen. The QObject docs are a >> good example of that, as they actually reference QWidget. Personally, I >> also regulary use the Inherited by list. I would hate to see that go. >> >> I don't have a solution ready though. >> > > > I also don't like it. What is the benefit of doing that? what went wrong with > make docs? There are 2 main problems with the current system: 1. Nobody was running "make docs" on their local machines (and verifying the output). There are qdoc errors that were put in by developers last December. Having the documentation modularized will at some point (hopefully soon) allow us to put documentation generation in the CI system. This would allow us to catch patches causing qdoc errors. 2. It was/is completely unclear how the system works, there hasn't been any QML documentation at http://doc-snapshot.qt-project.org/5.0/ for multiple weeks now (I believe 4, maybe more). > Also, you seem to use the "Module" terminology to refer to library (QtCore, > QtGui, ...) within qtbase. But some other people may refer to "Module" for > the repositoies (qtbase, qtdeclarative, qtscript, ...). > This is a bit confusing, please clarify. The term module in documentation equals library. There is no concept of repositories for the documentation. I went for what we use in qdoc (\module and \qmlmodule), sorry if that was unclear. Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
On Thursday 12 April 2012 15:35:45 André Somers wrote: > Op 12-4-2012 15:12, casper.vandonde...@nokia.com schreef: > > Modularizing the documentation is a process that will move a lot of files > > around and make some things impossible. > > The biggest consequence will be that we will have the same dependency > > chain as when compiling the modules. > > E.g. not allow circular dependencies in the documentation. Therefore there > > can be no links from the QtGui documentation to any class in QtWidgets, > > from QtWidgets to QtGui will work, since Widgets depends on Gui. > > This will also automatically break "Inherited by:" between classes in > > separate modules in the documentation. > > While I understand the reasoning, I am not sure the limitations above > are acceptable. At least, if I understand you correctly. > > I think that loosing all the cross links and all the inherited-by links > that span modules is unaceptable. For instance, you would no longer be > able to see relations between some major classes, like QObject -> > QWidget. You'd only be able to see QWidget -> QObject. These kinds of > links are not something that does not happen. The QObject docs are a > good example of that, as they actually reference QWidget. Personally, I > also regulary use the Inherited by list. I would hate to see that go. > > I don't have a solution ready though. > I also don't like it. What is the benefit of doing that? what went wrong with make docs? Also, you seem to use the "Module" terminology to refer to library (QtCore, QtGui, ...) within qtbase. But some other people may refer to "Module" for the repositoies (qtbase, qtdeclarative, qtscript, ...). This is a bit confusing, please clarify. ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] Towards a Qt 5 beta: Documentation
Op 12-4-2012 15:12, casper.vandonde...@nokia.com schreef: > Modularizing the documentation is a process that will move a lot of files > around and make some things impossible. > The biggest consequence will be that we will have the same dependency > chain as when compiling the modules. > E.g. not allow circular dependencies in the documentation. Therefore there > can be no links from the QtGui documentation to any class in QtWidgets, > from QtWidgets to QtGui will work, since Widgets depends on Gui. > This will also automatically break "Inherited by:" between classes in > separate modules in the documentation. While I understand the reasoning, I am not sure the limitations above are acceptable. At least, if I understand you correctly. I think that loosing all the cross links and all the inherited-by links that span modules is unaceptable. For instance, you would no longer be able to see relations between some major classes, like QObject -> QWidget. You'd only be able to see QWidget -> QObject. These kinds of links are not something that does not happen. The QObject docs are a good example of that, as they actually reference QWidget. Personally, I also regulary use the Inherited by list. I would hate to see that go. I don't have a solution ready though. André ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
