Documentation pluin (was Re: Status of the Source Formatter plugin)

[Alexander Dymo]

On Thursday 11 September 2008 21:51:35 Cedric Pasteur wrote:
> Right now, I plan to start woring on the documentation plugin. If there's
> another plugin more 'critical' for the future 4.0 that needs some love,
> please tell me.

Yeah, as Andreas says, filecreate would be more important. But should you 
start working on doc plugin, here's my experience with the one I wrote for 
KDev3. Hope that helps.


Good things:
- modular architecture with doc format plugins
- automatic discovery of installed documentation (it's not that hard as it 
sounds, but that code has to be now updated to match newer distributions)
- index with caching and optimizations


Bad things:
- documentation tree was the default display for the plugin (no idea who uses 
doc tree, it should be there of course, but I think the default view should be 
"Index"
- kdevtoc format 
it's a good idea in theory but in practice it doesn't work, it just pollutes 
the documentation tree and requires constant updates
- it should be easier to add documentation (ideally right from the doc tree 
instead of configuration dialog like in kdev3)
- full-text search with htdig
it requires setup, hence it's completely useless, we need to use something 
built-in (like strigi) for indexing local documentation, not htdig
- no Google search 
- Index and Search are two different tabs/interfaces
the difference between them is minimal, we need to merge that into the single 
interface that would immediatelly show results from disk index and 
asyncronously do local and Google search 


Undecided things and problems:
- documentation should reflect the set of features you're currently using in 
the IDE. KDev3 asks the project which language is set up for the project and 
shows only docs for that language. KDev4 doesn't have such luxury - our 
projects are now multilingual. Also the user can now open some file in some 
language at any time and KDevelop would load the lang support for it. Shall it 
also load language documentation? I don't know. It would be cool to hear some 
ideas...


Ideas:
- "webindex" format
just like we can search for "kde:kdiroperator" in Konqueror, we need to be 
able to do that from "Index" page in doc plugin. 
doc plugin would also support more smart search - like for "kde:ktexteditor" 
it would show "KTextEditor::Plugin", "KTextEditor::Document", etc. in the 
index


PS:
I think it may be practical to port existing code to KDE4 (requires only 
switching to model-view architecture), write the new Qt documentation plugin 
(understand new format), disable htdig search and remove kdevtoc stuff and 
then we can tackle all other problems later.