AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity
8324a93c73
gtk2/docs/reference/gtk/meson.build

112 lines
2.6 KiB
Meson
Raw Normal View History

Generate GTK API reference(s) with gi-docgen Stop using gtk-doc, and switch to gi-docgen. The gi-docgen tool generates API references through the introspection data, which has various benefits: - it does not parse C code - it does not generate and run C code to introspect types at build time - it does not present a different API from the one we're exporting Additionally, gi-docgen: - does not generate DocBook XML in order to generate HTML - does not go through xsltproc - parses proper Markdown Which makes it markedly faster than gtk-doc has ever been.
2021-02-10 13:41:53 +00:00
# XXX: gi-docgen needs a deps file
wip: Include markdown content, via pandoc Use pandoc to convert freestanding markdown files to docbook for inclusion in the generated docs, and use bits and pieces of gtk-doc code to continue expanding typical gtk-doc abbreviations. The new tool for markdown -> docbook is a python script called gtk-markdown-to-docbook. The markdown dialect is specified via a list of pandoc extension in gtk-markdown-to-docbook. It includes header annocations, definition lists and tables, among other things. This commit converts the 3 overview chapters (drawing, input handling and actions) and the migration guide to markdown syntax. Other files that are still listed in content_files can be converted later. This commit adds a pandoc dependency.
2020-05-23 01:56:39 +00:00
expand_content_md_files = [
docs: Drop gtk-doc files We don't use gtk-doc to generate our API reference, so we don't need its files lying around any more.
2021-02-18 12:59:09 +00:00
'overview.md',
docs: Convert platform sections to markdown
2020-05-24 14:55:02 +00:00
'broadway.md',
'osx.md',
'wayland.md',
'windows.md',
docs: Convert treeview and textview overview to markdown
2020-05-24 15:42:52 +00:00
'x11.md',
docs: Convert getting_started to markdown As part of the conversion, give up on including sources files from the examples directory, and instead include the content directly. All include mechanisms add complications. They were already complicated with xml, and markdown is not making things easier. We already did that for fragments, and if you make changes to these example sources, you probably need to revise the surrounding text anyway.
2020-05-24 04:22:31 +00:00
'getting_started.md',
docs: Drop gtk-doc files We don't use gtk-doc to generate our API reference, so we don't need its files lying around any more.
2021-02-18 12:59:09 +00:00
'initialization.md',
docs: Convert resources section to markdown
2020-05-24 15:07:45 +00:00
'resources.md',
docs: Convert building, compiling, running to markdown
2020-05-24 04:04:36 +00:00
'building.md',
'compiling.md',
'running.md',
wip: Include markdown content, via pandoc Use pandoc to convert freestanding markdown files to docbook for inclusion in the generated docs, and use bits and pieces of gtk-doc code to continue expanding typical gtk-doc abbreviations. The new tool for markdown -> docbook is a python script called gtk-markdown-to-docbook. The markdown dialect is specified via a list of pandoc extension in gtk-markdown-to-docbook. It includes header annocations, definition lists and tables, among other things. This commit converts the 3 overview chapters (drawing, input handling and actions) and the migration guide to markdown syntax. Other files that are still listed in content_files can be converted later. This commit adds a pandoc dependency.
2020-05-23 01:56:39 +00:00
'migrating-2to4.md',
'migrating-3to4.md',
'actions.md',
'input-handling.md',
docs: Convert css overview to markdown
2020-05-24 01:32:35 +00:00
'drawing-model.md',
'css-overview.md',
docs: Convert treeview and textview overview to markdown
2020-05-24 15:42:52 +00:00
'css-properties.md',
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
'section-accessibility.md',
docs: Convert treeview and textview overview to markdown
2020-05-24 15:42:52 +00:00
'section-text-widget.md',
'section-tree-widget.md',
docs: Add a listview overview section Add a conceptual overview for all the listmodel-based widgets. Fixes: #2214
2020-05-29 20:10:34 +00:00
'section-list-widget.md',
docs: Convert question index to markdown With this, the expand_content_files list has been completely converted to markdown files. Whats left in content_files is man pages, and a few special cases.
2020-05-24 18:25:25 +00:00
'question_index.md',
docs: Bring the widget gallery back We have all the images, lets put them to use.
2021-02-19 18:03:20 +00:00
'visual_index.md'
wip: Include markdown content, via pandoc Use pandoc to convert freestanding markdown files to docbook for inclusion in the generated docs, and use bits and pieces of gtk-doc code to continue expanding typical gtk-doc abbreviations. The new tool for markdown -> docbook is a python script called gtk-markdown-to-docbook. The markdown dialect is specified via a list of pandoc extension in gtk-markdown-to-docbook. It includes header annocations, definition lists and tables, among other things. This commit converts the 3 overview chapters (drawing, input handling and actions) and the migration guide to markdown syntax. Other files that are still listed in content_files can be converted later. This commit adds a pandoc dependency.
2020-05-23 01:56:39 +00:00
]
Generate screenshots on the fly This commit adds a new meson option -Dupdate_screenshots=true. When it is enabled, and -Dgtk_doc=true is also used, then the build will generate images to include in the API docs from ui files in docs/reference/gtk/images. Note: we still keep a copy of the images in git, in order to allow building without a display connection. To update the images in git, the generated images need to be copied back from the builddir to the srcdir.
2022-04-18 15:56:43 +00:00
gtk_images = []
subdir('images')
meson: Rename documentation option to gtk_doc This name is what most of the stack is using. Lets follow along, even though it is (imo) uglier.
2019-07-01 16:57:16 +00:00
if get_option('gtk_doc')
docs: Update the URLs of related projects for GTK And install the gi-docgen project file as well.
2021-07-31 18:08:34 +00:00
gtk4_toml = configure_file(
input: 'gtk4.toml.in',
output: 'gtk4.toml',
configuration: toml_conf,
install: true,
install_dir: docs_dir / 'gtk4',
)
Generate GTK API reference(s) with gi-docgen Stop using gtk-doc, and switch to gi-docgen. The gi-docgen tool generates API references through the introspection data, which has various benefits: - it does not parse C code - it does not generate and run C code to introspect types at build time - it does not present a different API from the one we're exporting Additionally, gi-docgen: - does not generate DocBook XML in order to generate HTML - does not go through xsltproc - parses proper Markdown Which makes it markedly faster than gtk-doc has ever been.
2021-02-10 13:41:53 +00:00
custom_target('gtk4-doc',
input: [ gtk4_toml, gtk_gir[0] ],
output: 'gtk4',
command: [
gidocgen,
'generate',
build: Collect gi-docgen's common arguments And only enable `--fatal-warnings` if `-Dwerror` has been set, just like we do for the introspection data generation.
2021-11-01 13:00:51 +00:00
gidocgen_common_args,
Generate GTK API reference(s) with gi-docgen Stop using gtk-doc, and switch to gi-docgen. The gi-docgen tool generates API references through the introspection data, which has various benefits: - it does not parse C code - it does not generate and run C code to introspect types at build time - it does not present a different API from the one we're exporting Additionally, gi-docgen: - does not generate DocBook XML in order to generate HTML - does not go through xsltproc - parses proper Markdown Which makes it markedly faster than gtk-doc has ever been.
2021-02-10 13:41:53 +00:00
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
Generate screenshots on the fly This commit adds a new meson option -Dupdate_screenshots=true. When it is enabled, and -Dgtk_doc=true is also used, then the build will generate images to include in the API docs from ui files in docs/reference/gtk/images. Note: we still keep a copy of the images in git, in order to allow building without a display connection. To update the images in git, the generated images need to be copied back from the builddir to the srcdir.
2022-04-18 15:56:43 +00:00
'--content-dir=@0@'.format(meson.current_build_dir()),
Generate GTK API reference(s) with gi-docgen Stop using gtk-doc, and switch to gi-docgen. The gi-docgen tool generates API references through the introspection data, which has various benefits: - it does not parse C code - it does not generate and run C code to introspect types at build time - it does not present a different API from the one we're exporting Additionally, gi-docgen: - does not generate DocBook XML in order to generate HTML - does not go through xsltproc - parses proper Markdown Which makes it markedly faster than gtk-doc has ever been.
2021-02-10 13:41:53 +00:00
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
build: Use a consistent style for Meson files
2020-12-15 12:31:38 +00:00
],
Generate screenshots on the fly This commit adds a new meson option -Dupdate_screenshots=true. When it is enabled, and -Dgtk_doc=true is also used, then the build will generate images to include in the API docs from ui files in docs/reference/gtk/images. Note: we still keep a copy of the images in git, in order to allow building without a display connection. To update the images in git, the generated images need to be copied back from the builddir to the srcdir.
2022-04-18 15:56:43 +00:00
depends: [ gdk_gir[0], gsk_gir[0] ] + gtk_images,
Generate GTK API reference(s) with gi-docgen Stop using gtk-doc, and switch to gi-docgen. The gi-docgen tool generates API references through the introspection data, which has various benefits: - it does not parse C code - it does not generate and run C code to introspect types at build time - it does not present a different API from the one we're exporting Additionally, gi-docgen: - does not generate DocBook XML in order to generate HTML - does not go through xsltproc - parses proper Markdown Which makes it markedly faster than gtk-doc has ever been.
2021-02-10 13:41:53 +00:00
depend_files: [ expand_content_md_files ],
build_by_default: true,
build: Install the API references We are building them, but not installing them.
2021-03-12 11:13:54 +00:00
install: true,
install_dir: docs_dir,
build: Use a consistent style for Meson files
2020-12-15 12:31:38 +00:00
)
meson: allow building man pages without the documentation The 'documentation' option also guarded the man page build. Instead if skipping the whole docs subdir skip the specific gtkdoc calls, so that the man page build still works. This brings it in line with the gtk3 meson build.
2019-05-25 16:27:32 +00:00
endif
meson: Generate man pages for the installed tools
2017-05-05 10:34:05 +00:00
Check for 'rst2man' misses installed 'rst2man.py' (#4728) By default, 'docutils' installs 'rst2man' as 'rst2man.py'. Amend the check for 'rst2man' to look for 'rst2man.py' as well if 'rst2man' is not found.
2022-03-19 10:41:32 +00:00
rst2man = find_program('rst2man', 'rst2man.py', required: false)
Switch man pages to reStructuredFormat It's easier to write than DocBook, and rst2man is faster than xsltproc.
2021-09-24 16:54:41 +00:00
if get_option('man-pages') and not rst2man.found()
error('No rst2man found, but man pages were explicitly enabled')
meson: Generate man pages for the installed tools
2017-05-05 10:34:05 +00:00
endif
Switch man pages to reStructuredFormat It's easier to write than DocBook, and rst2man is faster than xsltproc.
2021-09-24 16:54:41 +00:00
if get_option('man-pages') and rst2man.found()
rst_files = [
[ 'gtk4-broadwayd', '1' ],
[ 'gtk4-builder-tool', '1' ],
meson: Generate man pages for the installed tools
2017-05-05 10:34:05 +00:00
[ 'gtk4-encode-symbolic-svg', '1', ],
[ 'gtk4-launch', '1', ],
[ 'gtk4-query-settings', '1', ],
[ 'gtk4-update-icon-cache', '1', ],
]
meson: only build demo manpages when demos are enabled Installing them even when manpages are enabled, but the demos are disabled, produces manpages for unavailable programs...
2021-04-14 02:48:39 +00:00
if get_option('demos')
Switch man pages to reStructuredFormat It's easier to write than DocBook, and rst2man is faster than xsltproc.
2021-09-24 16:54:41 +00:00
rst_files += [
meson: only build demo manpages when demos are enabled Installing them even when manpages are enabled, but the demos are disabled, produces manpages for unavailable programs...
2021-04-14 02:48:39 +00:00
[ 'gtk4-demo', '1', ],
[ 'gtk4-demo-application', '1', ],
[ 'gtk4-widget-factory', '1', ],
[ 'gtk4-icon-browser', '1', ],
Add a man page for gtk4-node-editor
2022-05-07 03:48:13 +00:00
[ 'gtk4-node-editor', '1', ],
meson: only build demo manpages when demos are enabled Installing them even when manpages are enabled, but the demos are disabled, produces manpages for unavailable programs...
2021-04-14 02:48:39 +00:00
]
endif
Switch man pages to reStructuredFormat It's easier to write than DocBook, and rst2man is faster than xsltproc.
2021-09-24 16:54:41 +00:00
rst2man_flags = [
'--syntax-highlight=none',
]
foreach rst: rst_files
man_name = rst[0]
man_section = rst.get(1, '1')
custom_target('man-@0@'.format(man_name),
input: '@0@.rst'.format(man_name),
build: Use a consistent style for Meson files
2020-12-15 12:31:38 +00:00
output: '@0@.@1@'.format(man_name, man_section),
command: [
Switch man pages to reStructuredFormat It's easier to write than DocBook, and rst2man is faster than xsltproc.
2021-09-24 16:54:41 +00:00
rst2man,
rst2man_flags,
build: Use a consistent style for Meson files
2020-12-15 12:31:38 +00:00
'@INPUT@',
],
Switch man pages to reStructuredFormat It's easier to write than DocBook, and rst2man is faster than xsltproc.
2021-09-24 16:54:41 +00:00
capture: true,
build: Use a consistent style for Meson files
2020-12-15 12:31:38 +00:00
install: true,
Switch man pages to reStructuredFormat It's easier to write than DocBook, and rst2man is faster than xsltproc.
2021-09-24 16:54:41 +00:00
install_dir: get_option('mandir') / 'man@0@'.format(man_section),
build: Use a consistent style for Meson files
2020-12-15 12:31:38 +00:00
)
meson: Generate man pages for the installed tools
2017-05-05 10:34:05 +00:00
endforeach
endif
Reference in New Issue Copy Permalink