diff mbox

[v4,2/2] doc: separate pure API guide and implementation guide

Message ID 1465846654-13389-2-git-send-email-mike.holmes@linaro.org
State Accepted
Commit 793c4b15275fd7e6c30bf348f236e778b9bfee02
Headers show

Commit Message

Mike Holmes June 13, 2016, 7:37 p.m. UTC 
It should be possible to generate the pure API specification guide, this
patch achieves that

Copy the application guide to form a platform specific guide.
The application guide is now ONLY the public specification.
The new platform guide includes the additional definitions specific to
odp-linux and it can contain platform specific notes and other
documentation as needed

Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
---
v4
   Subject change from  Christophe
   Bug fixes uncovered in better testing - prior patch

Christophe, I dropped your review because I had changed a few things.
I moved the common doxygen up a level for one.


 configure.ac                       |  4 ++-
 doc/Doxyfile_common                | 32 ++++++++++++++++++++++++
 doc/Makefile.am                    |  5 ++--
 doc/application-api-guide/Doxyfile | 50 ++++++--------------------------------
 doc/m4/configure.m4                |  1 +
 doc/platform-api-guide/.gitignore  |  1 +
 doc/platform-api-guide/Doxyfile    | 19 +++++++++++++++
 doc/platform-api-guide/Makefile.am |  5 ++++
 8 files changed, 71 insertions(+), 46 deletions(-)
 create mode 100644 doc/Doxyfile_common
 create mode 100644 doc/platform-api-guide/.gitignore
 create mode 100644 doc/platform-api-guide/Doxyfile
 create mode 100644 doc/platform-api-guide/Makefile.am
diff mbox

Patch

diff --git a/configure.ac b/configure.ac
index a12f984..da08d39 100644
--- a/configure.ac
+++ b/configure.ac
@@ -183,7 +183,9 @@  DX_INIT_DOXYGEN($PACKAGE_NAME,
 		${srcdir}/doc/application-api-guide/Doxyfile,
 		${builddir}/doc/application-api-guide/output,
 		${srcdir}/doc/helper-guide/Doxyfile,
-		${builddir}/doc/helper-guide/output)
+		${builddir}/doc/helper-guide/output,
+		${srcdir}/doc/platform-api-guide/Doxyfile,
+		${builddir}/doc/platform-api-guide/output)
 
 ##########################################################################
 # Enable/disable ODP_DEBUG_PRINT
diff --git a/doc/Doxyfile_common b/doc/Doxyfile_common
new file mode 100644
index 0000000..5955853
--- /dev/null
+++ b/doc/Doxyfile_common
@@ -0,0 +1,32 @@ 
+QUIET = YES
+OUTPUT_DIRECTORY = $(DOCDIR)
+FULL_PATH_NAMES = NO
+JAVADOC_AUTOBRIEF = YES
+OPTIMIZE_OUTPUT_FOR_C = YES
+TYPEDEF_HIDES_STRUCT = NO
+EXTRACT_STATIC = YES
+SORT_MEMBER_DOCS = NO
+WARN_NO_PARAMDOC = YES
+FILE_PATTERNS = *.h odp*.c *.dox
+RECURSIVE = YES
+SOURCE_BROWSER = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION = YES
+ALPHABETICAL_INDEX = NO
+QHP_NAMESPACE =
+GENERATE_TREEVIEW = YES
+PAPER_TYPE = a4wide
+CLASS_DIAGRAMS = NO
+HAVE_DOT = YES
+CALL_GRAPH = YES
+DOT_MULTI_TARGETS = NO
+EXAMPLE_PATTERNS = *.c
+EXAMPLE_RECURSIVE = YES
+IMAGE_PATH = $(SRCDIR)/doc/images
+HTML_EXTRA_STYLESHEET = $(SRCDIR)/doc/odpdoxygen.css
+LAYOUT_FILE = $(SRCDIR)/doc/doxygenlayout.xml
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+INTERNAL_DOCS = YES
+DOT_IMAGE_FORMAT = svg
diff --git a/doc/Makefile.am b/doc/Makefile.am
index cf67c42..d49d84b 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,4 @@ 
-SUBDIRS = application-api-guide helper-guide
+SUBDIRS = application-api-guide helper-guide platform-api-guide
 
 if user_guide
 SUBDIRS += implementers-guide users-guide process-guide
@@ -7,4 +7,5 @@  endif
 EXTRA_DIST = \
 	   $(top_srcdir)/doc/doxygenlayout.xml \
 	   $(top_srcdir)/doc/odpdoxygen.css \
-	   $(top_srcdir)/doc/glossary.adoc
+	   $(top_srcdir)/doc/glossary.adoc \
+	   $(top_srcdir)/doc/Doxyfile_common
diff --git a/doc/application-api-guide/Doxyfile b/doc/application-api-guide/Doxyfile
index 97731b2..9cb183c 100644
--- a/doc/application-api-guide/Doxyfile
+++ b/doc/application-api-guide/Doxyfile
@@ -1,48 +1,12 @@ 
-PROJECT_NAME = "API Reference Manual for $(WITH_PLATFORM)"
+@INCLUDE = $(SRCDIR)/doc/Doxyfile_common
+
+PROJECT_NAME = "API Reference Manual"
 PROJECT_NUMBER = $(VERSION)
 PROJECT_LOGO = $(SRCDIR)/doc/images/ODP-Logo-HQ.svg
-QUIET = YES
-OUTPUT_DIRECTORY = $(DOCDIR)
-FULL_PATH_NAMES = NO
-JAVADOC_AUTOBRIEF = YES
-OPTIMIZE_OUTPUT_FOR_C = YES
-TYPEDEF_HIDES_STRUCT = NO
-EXTRACT_STATIC = YES
-SORT_MEMBER_DOCS = NO
-WARN_NO_PARAMDOC = YES
 INPUT = $(SRCDIR)/doc/application-api-guide \
-	$(SRCDIR)/include \
-	$(SRCDIR)/platform/$(WITH_PLATFORM)/include/odp \
-	$(SRCDIR)/platform/$(WITH_PLATFORM)/arch/$(WITH_ARCH)
-FILE_PATTERNS = *.h odp*.c *.dox
-RECURSIVE = YES
-SOURCE_BROWSER = YES
-REFERENCED_BY_RELATION = YES
-REFERENCES_RELATION = YES
-ALPHABETICAL_INDEX = NO
-QHP_NAMESPACE =
-GENERATE_TREEVIEW = YES
-PAPER_TYPE = a4wide
-CLASS_DIAGRAMS = NO
-HAVE_DOT = YES
-CALL_GRAPH = YES
-DOT_MULTI_TARGETS = NO
-EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform $(SRCDIR)
-EXAMPLE_PATTERNS = *.c
-EXAMPLE_RECURSIVE = YES
-IMAGE_PATH = $(SRCDIR)/doc/images
-HTML_EXTRA_STYLESHEET = $(SRCDIR)/doc/odpdoxygen.css
-LAYOUT_FILE = $(SRCDIR)/doc/doxygenlayout.xml
-ENABLE_PREPROCESSING = YES
-MACRO_EXPANSION = YES
-EXPAND_ONLY_PREDEF = YES
+	$(SRCDIR)/include
+EXCLUDE_PATTERNS = drv* odp_drv.h
+EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)
 PREDEFINED = __GNUC__ \
-	     __attribute__(x)= \
-	     ODP_ALIGNED(x)= \
-	     __BIG_ENDIAN_BITFIELD \
-	     __LITTLE_ENDIAN_BITFIELD \
-	     __x86_64__ \
-	     ODP_PACKED \
 	     "ODP_HANDLE_T(type)=odp_handle_t type"
-INTERNAL_DOCS = YES
-DOT_IMAGE_FORMAT = svg
+WARNINGS = NO
diff --git a/doc/m4/configure.m4 b/doc/m4/configure.m4
index 183c929..ed9451d 100644
--- a/doc/m4/configure.m4
+++ b/doc/m4/configure.m4
@@ -40,5 +40,6 @@  AC_CONFIG_FILES([doc/application-api-guide/Makefile
 		 doc/helper-guide/Makefile
 		 doc/implementers-guide/Makefile
 		 doc/Makefile
+		 doc/platform-api-guide/Makefile
 		 doc/process-guide/Makefile
 		 doc/users-guide/Makefile])
diff --git a/doc/platform-api-guide/.gitignore b/doc/platform-api-guide/.gitignore
new file mode 100644
index 0000000..53752db
--- /dev/null
+++ b/doc/platform-api-guide/.gitignore
@@ -0,0 +1 @@ 
+output
diff --git a/doc/platform-api-guide/Doxyfile b/doc/platform-api-guide/Doxyfile
new file mode 100644
index 0000000..b87b7b2
--- /dev/null
+++ b/doc/platform-api-guide/Doxyfile
@@ -0,0 +1,19 @@ 
+@INCLUDE = $(SRCDIR)/doc/Doxyfile_common
+
+PROJECT_NAME = "API Reference Manual for $(WITH_PLATFORM)"
+PROJECT_NUMBER = $(VERSION)
+PROJECT_LOGO = $(SRCDIR)/doc/images/ODP-Logo-HQ.svg
+INPUT = $(SRCDIR)/doc/application-api-guide \
+	$(SRCDIR)/doc/platform-api-guide \
+	$(SRCDIR)/include \
+	$(SRCDIR)/platform/$(WITH_PLATFORM)/include/odp \
+	$(SRCDIR)/platform/$(WITH_PLATFORM)/arch/$(WITH_ARCH)
+EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform $(SRCDIR)
+PREDEFINED = __GNUC__ \
+	     __attribute__(x)= \
+	     ODP_ALIGNED(x)= \
+	     __BIG_ENDIAN_BITFIELD \
+	     __LITTLE_ENDIAN_BITFIELD \
+	     __x86_64__ \
+	     ODP_PACKED \
+	     "ODP_HANDLE_T(type)=odp_handle_t type"
diff --git a/doc/platform-api-guide/Makefile.am b/doc/platform-api-guide/Makefile.am
new file mode 100644
index 0000000..a04c254
--- /dev/null
+++ b/doc/platform-api-guide/Makefile.am
@@ -0,0 +1,5 @@ 
+EXTRA_DIST = \
+	     Doxyfile
+
+clean-local:
+	rm -rf output