GNOME Bugzilla – Bug 725665
Host GJS documentation
Last modified: 2018-09-24 10:38:34 UTC
GJS documentation is generated through g-ir-doc-tool from gir files (which are not part of the tarballs because they are partially platform and arch-dependent), as well as manual editing. It is in mallard form, and partially lives in the gjs-documentation repository (only the manually edited parts are there, for the fully automated libraries there are only the scripts) To go from a tarball to a GIR file, one needs the full GNOME build environment, because g-ir-scanner needs to build the library to introspect it. To go from a GIR file to mallard files, one needs g-ir-doc-tool. The only dependencies are python2, mako, maybe elementtree? To go from mallard files to HTML, one needs yelp-build. I believe this is already used in library-web? Deps are yelp-xsl and xsltproc. We can decide at which level put the manual interaction, and for example store GIR files of the documented libraries at API freeze in the gjs-documentation repository. Storing full mallard files is a bit more complex, they take a lot of space and pollute the git history.
Somewhat off-topic but: as I asked on d-d-l, do you plan to include libatspi on this GJS documentation? Is that is the case, I would like to close bug 703422 as a duplicate of this bug.
(In reply to comment #1) > Somewhat off-topic but: as I asked on d-d-l, do you plan to include libatspi on > this GJS documentation? Is that is the case, I would like to close bug 703422 > as a duplicate of this bug. If docs are moved to developer.gnome.org, any library that has C docs there would be a candidate for GJS docs. OTOH, people.gnome.org is a different machine and has limited space, so I'd like to keep the library count down for now.
(In reply to comment #2) > (In reply to comment #1) > > Somewhat off-topic but: as I asked on d-d-l, do you plan to include libatspi on > > this GJS documentation? Is that is the case, I would like to close bug 703422 > > as a duplicate of this bug. > > If docs are moved to developer.gnome.org, any library that has C docs there > would be a candidate for GJS docs. Ok. > OTOH, people.gnome.org is a different > machine and has limited space, so I'd like to keep the library count down for > now. No problem. I know that this is still an WIP. And again, thanks for your work.
*** Bug 703422 has been marked as a duplicate of this bug. ***
(In reply to comment #0) > To go from a GIR file to mallard files, one needs g-ir-doc-tool. The only > dependencies are python2, mako, maybe elementtree? Ok, that will be fine for the server, and that's the right point to start. > We can decide at which level put the manual interaction, and for example store > GIR files of the documented libraries at API freeze in the gjs-documentation > repository. Storing full mallard files is a bit more complex, they take a lot > of space and pollute the git history. Ideally we would have gir files arranged by versions (as developer.gnome.org also gives access to older docs) and accessible from webapps.gnome.org; this can be in git or anywhere, I didn't give much thoughts to that. Also we should match the various libraries to their gtk-doc DOC_MODULE (used in developer.gnome.org URLs) (exeample Gtk-3.0 → gtk3), is this something doable? Those two things will also have consequences on crosslinking from a module to another, as the URL won't be the same at all, I didn't look at they way it's done at the moment.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/Infrastructure/Websites/issues/146.