[PATCH 2/2] Add api-doc class

[PATCH 2/2] Add api-doc class

[b40527]

From: Zongchun Yu <Zongchun.Yu@freescale.com>

this class use doxygen to generate api docs from source code

Signed-off-by: Zongchun Yu <Zongchun.Yu@freescale.com>
---
 meta/classes/api-doc.bbclass |   16 ++++++++++++++++
 1 files changed, 16 insertions(+), 0 deletions(-)
 create mode 100644 meta/classes/api-doc.bbclass

diff --git a/meta/classes/api-doc.bbclass b/meta/classes/api-doc.bbclass
new file mode 100644
index 0000000..0879c3e
--- /dev/null
+++ b/meta/classes/api-doc.bbclass
@@ -0,0 +1,16 @@
+# Helper class to pull in the right dependencies and generate
+# api documentation from sources code
+
+DEPENDS += "doxygen-native"
+
+# Doxygen configuration file
+DOXYGEN_CFG ?= "Doxyfile"
+
+do_generate_doc () {
+    if [ -e ${S}/${DOXYGEN_CFG} ]; then
+        doxygen ${S}/${DOXYGEN_CFG}
+    else
+        bbfatal "no doxygen configuration file found"
+    fi
+}
+addtask generate_doc before do_install after do_patch
-- 
1.7.0.4

Re: [PATCH 2/2] Add api-doc class

[Burton, Ross]

As this class is specific to doxygen, please call it doxygen.bbclass.

Also I think this should be opt-in not forcibly enabled as not
everyone would want API documentation to be generated.

Pretty sure you'll want to run doxygen after do_compile in case the
documentation is generated from files built at compile time.  But
don't most packages that use doxygen invoke it themselves?  You're
also not actually installing the documentation anywhere.

Ross

On 16 May 2014 08:45,  <b40527@freescale.com> wrote:
> From: Zongchun Yu <Zongchun.Yu@freescale.com>
>
> this class use doxygen to generate api docs from source code
>
> Signed-off-by: Zongchun Yu <Zongchun.Yu@freescale.com>
> ---
>  meta/classes/api-doc.bbclass |   16 ++++++++++++++++
>  1 files changed, 16 insertions(+), 0 deletions(-)
>  create mode 100644 meta/classes/api-doc.bbclass
>
> diff --git a/meta/classes/api-doc.bbclass b/meta/classes/api-doc.bbclass
> new file mode 100644
> index 0000000..0879c3e
> --- /dev/null
> +++ b/meta/classes/api-doc.bbclass
> @@ -0,0 +1,16 @@
> +# Helper class to pull in the right dependencies and generate
> +# api documentation from sources code
> +
> +DEPENDS += "doxygen-native"
> +
> +# Doxygen configuration file
> +DOXYGEN_CFG ?= "Doxyfile"
> +
> +do_generate_doc () {
> +    if [ -e ${S}/${DOXYGEN_CFG} ]; then
> +        doxygen ${S}/${DOXYGEN_CFG}
> +    else
> +        bbfatal "no doxygen configuration file found"
> +    fi
> +}
> +addtask generate_doc before do_install after do_patch
> --
> 1.7.0.4
>
> --
> _______________________________________________
> Openembedded-core mailing list
> Openembedded-core@lists.openembedded.org
> http://lists.openembedded.org/mailman/listinfo/openembedded-core

Re: [PATCH 2/2] Add api-doc class

[Zongchun YU]

>>As this class is specific to doxygen, please call it doxygen.bbclass.
[Zongchun] I agree and will change it in the next patch.
>>Also I think this should be opt-in not forcibly enabled as not everyone would want API documentation to be generated.
[Zongchun] Yes. it is opt-in. the source code of packages should be written follow the rules of doxygen. If not. doxygen will not generate docs.
>>Pretty sure you'll want to run doxygen after do_compile in case the documentation is generated from files built at compile time.  But don't most packages that use doxygen invoke it themselves?  You're also not actually installing the documentation anywhere.
[Zongchun] doxygen just use source code(follow the rules of doxygen) of packages to generate docs. not use files built at compile time. Some packages may just need to fetch and patch the source code and then generate docs. the configure file of doxygen have options to specify the generated docs types and location. Whether install the docs may depend the packages.

Re: [PATCH 2/2] Add api-doc class

[Burton, Ross]

On 16 May 2014 11:18, Zongchun YU <b40527@freescale.com> wrote:
>>>Also I think this should be opt-in not forcibly enabled as not everyone would want API documentation to be generated.
> [Zongchun] Yes. it is opt-in. the source code of packages should be written follow the rules of doxygen. If not. doxygen will not generate docs.

It's not opt-in: once a recipe is using doxygen.bbclass then it has a
build dependency on doxygen-native and *will* generate documentation.
This is needless overhead if you don't intend to read the
documentation.


>>>Pretty sure you'll want to run doxygen after do_compile in case the documentation is generated from files built at compile time.  But don't most packages that use doxygen invoke it themselves?  You're also not actually installing the documentation anywhere.
> [Zongchun] doxygen just use source code(follow the rules of doxygen) of packages to generate docs. not use files built at compile time. Some packages may just need to fetch and patch the source code and then generate docs. the configure file of doxygen have options to specify the generated docs types and location. Whether install the docs may depend the packages.

You can't assert that the documentation is solely generated on the
shipped files in the tarballs: what if some of the files are
machine-generated?  Or if with for example DBus, the doxygen is
generated?

I've nothing against a doxygen class and would like to also see a
gtk-doc class that isn't a stub, with a single distribution-level
"generate API documentation" variable controlling them.  But the
documentation has to be generated at build time, and I think it's fair
to assume that is a package has API documentation then "make" will
build it, otherwise the method to build the documentation will be
different for every package.

For example, DBus has a Doxyfile.in at the top of the source tree, so
not only does configure needs to run to generate a Doxyfile but that
Doxyfile is written to ${B}, not ${S}.

Ross

Re: [PATCH 2/2] Add api-doc class

[Zongchun YU]

>It's not opt-in: once a recipe is using doxygen.bbclass then it has a build dependency on doxygen-native and *will* generate documentation.
>This is needless overhead if you don't intend to read the documentation.

I think if you intend to read the documentation. Just inherit this class. If not. there is no need to inherit this class.

>You can't assert that the documentation is solely generated on the shipped files in the tarballs: what if some of the files are machine-generated?  Or if with for example DBus, the doxygen is generated?
>I've nothing against a doxygen class and would like to also see a gtk-doc class that isn't a stub, with a single distribution-level "generate API documentation" variable controlling them.  But the documentation has to be generated at build time, and I think it's fair to assume that is a package has API documentation then "make" will build it, otherwise the method to build the documentation will be different for every package.
>For example, DBus has a Doxyfile.in at the top of the source tree, so not only does configure needs to run to generate a Doxyfile but that Doxyfile is written to ${B}, not ${S}.

OK. You are right. What about configure task? Maybe we should adjust this task before it. Doxyfile(or other name) is the file which will be used by doxygen. It is one part of source code to be maintain.

Zongchun

Re: [PATCH 2/2] Add api-doc class

[Burton, Ross]

On 19 May 2014 04:18, Zongchun YU <b40527@freescale.com> wrote:
>>It's not opt-in: once a recipe is using doxygen.bbclass then it has a build dependency on doxygen-native and *will* generate documentation.
>>This is needless overhead if you don't intend to read the documentation.
>
> I think if you intend to read the documentation. Just inherit this class. If not. there is no need to inherit this class.

So you're suggesting that if a user wants documentation generated they
should know what recipes they can add "inherit api-doc" to?

I'll repeat my proposal: every recipe that can generate doxygen
documentation inherits a doxygen class, and that class can look at a
distro-level variable along the likes of GENERATE_API_DOCS (which a
hypothetical non-stub gtk-doc class can also respect).

>>You can't assert that the documentation is solely generated on the shipped files in the tarballs: what if some of the files are machine-generated?  Or if with for example DBus, the doxygen is generated?
>>I've nothing against a doxygen class and would like to also see a gtk-doc class that isn't a stub, with a single distribution-level "generate API documentation" variable controlling them.  But the documentation has to be generated at build time, and I think it's fair to assume that is a package has API documentation then "make" will build it, otherwise the method to build the documentation will be different for every package.
>>For example, DBus has a Doxyfile.in at the top of the source tree, so not only does configure needs to run to generate a Doxyfile but that Doxyfile is written to ${B}, not ${S}.
>
> OK. You are right. What about configure task? Maybe we should adjust this task before it. Doxyfile(or other name) is the file which will be used by doxygen. It is one part of source code to be maintain.

Give me ten minutes and I'll find a package that builds documentation
from a file generated at build time.

Are there really that many recipes that support doxygen but don't run
it themselves at build time? I'd have expected packages that can use
doxygen to generate the documentation at build time (using DBus as an
example, if it finds doxygen at configure time it will build
documentation).

Ross

Re: [PATCH 2/2] Add api-doc class

[Zongchun YU]

>>It's not opt-in: once a recipe is using doxygen.bbclass then it has a build dependency on doxygen-native and *will* generate documentation.
>>This is needless overhead if you don't intend to read the documentation.
>
> I think if you intend to read the documentation. Just inherit this class. If not. there is no need to inherit this class.

So you're suggesting that if a user wants documentation generated they should know what recipes they can add "inherit api-doc" to?

I'll repeat my proposal: every recipe that can generate doxygen documentation inherits a doxygen class, and that class can look at a distro-level variable along the likes of GENERATE_API_DOCS (which a hypothetical non-stub gtk-doc class can also respect).
[Zongchun] OK. Can you explain the details to use GENERATE_API_DOCS? I am not sure the meaning. Thanks.

Re: [PATCH 2/2] Add api-doc class

[Burton, Ross]

On 23 May 2014 06:45, Zongchun YU <b40527@freescale.com> wrote:
> OK. Can you explain the details to use GENERATE_API_DOCS? I am not sure the meaning.

We'd have a distro-level variable GENERATE_API_DOCS.  It can default
to 0, but distros or users can set it to 1 in their own distro or
local.conf and then all recipes that have API documentation, can
generate API documentation.

Alternatively, it could be set per-recipe if you only wanted to enable
some documentation, i.e. GENERATE_API_DOCS_pn-glib-2.0 = "1" would be
used to generate just glib-2.0 documentation.

Ross

[PATCH 2/2] Add api-doc class

[b40527]

From: Zongchun Yu <Zongchun.Yu@freescale.com>

this class use doxygen to generate api docs from source code

Signed-off-by: Zongchun Yu <Zongchun.Yu@freescale.com>
---
 meta/classes/api-doc.bbclass |   16 ++++++++++++++++
 1 files changed, 16 insertions(+), 0 deletions(-)
 create mode 100644 meta/classes/api-doc.bbclass

diff --git a/meta/classes/api-doc.bbclass b/meta/classes/api-doc.bbclass
new file mode 100644
index 0000000..0879c3e
--- /dev/null
+++ b/meta/classes/api-doc.bbclass
@@ -0,0 +1,16 @@
+# Helper class to pull in the right dependencies and generate
+# api documentation from sources code
+
+DEPENDS += "doxygen-native"
+
+# Doxygen configuration file
+DOXYGEN_CFG ?= "Doxyfile"
+
+do_generate_doc () {
+    if [ -e ${S}/${DOXYGEN_CFG} ]; then
+        doxygen ${S}/${DOXYGEN_CFG}
+    else
+        bbfatal "no doxygen configuration file found"
+    fi
+}
+addtask generate_doc before do_install after do_patch
-- 
1.7.0.4