Merge pull request #36 from Cogmasters/fix_docs_gen

Fix docs gen

.github/workflows/gh_pages.yml

@@ -13,23 +13,34 @@ jobs:
     steps:
       - uses: actions/checkout@v1
 
-      - name: Dependencies
+      - name: Install Doxygen-1.9.3
+        run: |
+          echo "Install wget"
+          sudo apt install wget
+          echo "Fetching binary distribution"
+          wget https://www.doxygen.nl/files/doxygen-1.9.3.linux.bin.tar.gz
+          echo "Extract files from tar file"
+          tar -xvf doxygen-1.9.3.linux.bin.tar.gz
+
+      - name: Install Jinja2
+        run: pip install -U jinja2
+
+      - name: Install Sphinx
         run: |
-          echo "Preparing files for documentation"
-          make docs
-          echo "Install Jinja2"
-          pip install -U jinja2
-          echo "Install Sphinx"
           pip install sphinx
           pip install pydata_sphinx_theme
-          echo "Install Breathe"
-          pip install breathe
 
-      - name: Doxygen Action
-        uses: mattnotmitt/doxygen-action@v1.3.1
+      - name: Install Breathe
+        run: pip install breathe
 
-      - name: Move XML to Concord-Docs
-        run: sudo mv docs/xml concord-docs/docs
+      - name: Doxygen Action
+        run: |
+          echo "Preparing files for documentation"
+          make docs
+          mv doxygen-1.9.3/bin/doxygen .
+          echo "Generating XML output"
+          ./doxygen
+          sudo mv docs/xml concord-docs/docs
 
       - name: Breathe Action
         run: make -C concord-docs/docs html

gencodecs/Makefile

@@ -82,7 +82,7 @@ $(HEADERS): $(PP)
 .pre.h.h:
 	@ echo "#ifndef $(HEADER_TAG)" > $(DOCS_DIR)/$@
 	@ echo "#define $(HEADER_TAG)" >> $(DOCS_DIR)/$@
-	$(CPP) $(CFLAGS) -DGENCODECS_HEADER -DGENCODECS_READ=\"$<\" -nostdinc -P $(INP_PRE) | $(PP) >> $(DOCS_DIR)/$@
+	$(CPP) $(CFLAGS) -DGENCODECS_HEADER -DGENCODECS_READ=\"$<\" -nostdinc -P -CC $(INP_PRE) | $(PP) >> $(DOCS_DIR)/$@
 	@ echo "#endif /* $(HEADER_TAG) */" >> $(DOCS_DIR)/$@
 
 echo:

gencodecs/api/channel.pre.h

@@ -97,6 +97,7 @@ ENUM(discord_message_flags)
                     = 1 << 8)
 ENUM_END
 
+/** @CCORD_pub_methods{discord_channel} */
 PUB_STRUCT(discord_channel)
   PP("the ID of this channel")
     FIELD_SNOWFLAKE(id)

gencodecs/discord-codecs.pre.h

@@ -9,6 +9,31 @@ PP_INCLUDE("common.h")
 PP_INCLUDE("cog-utils.h")
 #endif
 
+#define RST_PUB_STRUCT(_type) \
+"@verbatim embed:rst" \
+".. container:: toggle" \
+"" \
+"  .. container:: header" \
+"" \
+"    **Methods**" \
+"" \
+"  - Initializer:" \
+"" \
+"    - :code:`void discord_channel_init(struct discord_channel *)`" \
+"  - Cleanup:" \
+"" \
+"    - :code:`void discord_channel_cleanup(struct discord_channel *)`" \
+"  - JSON Decoder:" \
+"" \
+"    - :code:`size_t discord_channel_from_json(char *rbuf, size_t len, struct discord_channel *)`" \
+"    - :code:`size_t discord_channel_from_jsmnf(jsmnf *root, char *rbuf, struct discord_channel *)`" \
+"  - JSON Encoder:" \
+"" \
+"    - :code:`size_t discord_channel_to_json(char *wbuf, size_t len, struct discord_channel *)`" \
+"    - :code:`jsonbcode discord_channel_to_jsonb(jsonb *b, char *wbuf, size_t len, struct discord_channel *)`" \
+"@endverbatim"
+
+/* Custom JSON encoding macros */
 #define JSON_ENCODER_PTR_json_char(b, buf, size, _var, _type)                 \
     if (0 > (code = jsonb_token(b, buf, size, _var, strlen(_var))))           \
         return code
@@ -29,6 +54,7 @@ PP_INCLUDE("cog-utils.h")
                 return code;                                                  \
         }
 
+/* Custom JSON decoding macros */
 #define JSON_DECODER_PTR_json_char(f, buf, _var, _type)                       \
     if (f) {                                   \
         _var = _gc_strndup(buf + f->val->start, f->val->end - f->val->start); \
@@ -41,13 +67,15 @@ PP_INCLUDE("cog-utils.h")
         cog_iso8601_to_unix_ms(buf + f->val->start,                           \
                                  f->val->end - f->val->start, &_var)
 
+/* Custom field macros */
 #define FIELD_SNOWFLAKE(_name)                                                \
     FIELD_PRINTF(_name, u64snowflake, "\"%" PRIu64 "\"", "%" SCNu64)
 #define FIELD_TIMESTAMP(_name)                                                \
     FIELD_CUSTOM(_name, #_name, u64unix_ms, DECOR_BLANK, INIT_BLANK,          \
                  CLEANUP_BLANK, JSON_ENCODER_u64unix_ms,                      \
                  JSON_DECODER_u64unix_ms, (u64unix_ms)0)
 
+/* if GENCODECS_READ is not specified then generate for all files */
 #ifndef GENCODECS_READ
 #   define GENCODECS_READ "all.pre.h"
 #endif

gencodecs/gencodecs-pp.c

@@ -67,11 +67,18 @@ main(void)
         while (*p) {
             switch (*p) {
             case '"':
-                if (state & STRING)
+                if (state & STRING) {
+                    if (state & DESC) 
+                        fputc('\n', stdout);
+                    else
+                        fputc(*p, stdout);
                     state &= ~STRING;
-                else
+                }
+                else {
+                    if (!(state & DESC)) 
+                        fputc(*p, stdout);
                     state |= STRING;
-                if (!(state & DESC)) fputc(*p, stdout);
+                }
                 ++p;
                 break;
             case '(':

gencodecs/recipes/struct.h

@@ -1,4 +1,3 @@
-#define BLANK
 #define INIT_BLANK(_var, _type)
 #define CLEANUP_BLANK(_var, _type)
 
@@ -13,14 +12,6 @@
 #ifdef GENCODECS_DATA
 #ifdef GENCODECS_HEADER
 
-#define GENCODECS_STRUCT(_type) struct _type;
-#define GENCODECS_LIST(_type)   struct _type;
-
-#define GENCODECS_PUB_STRUCT(_type) GENCODECS_STRUCT(_type)
-#define GENCODECS_PUB_LIST(_type) GENCODECS_LIST(_type)
-
-#include "gencodecs-gen.pre.h"
-
 #define GENCODECS_STRUCT(_type)                                               \
     struct _type {
 #define GENCODECS_FIELD(_name, _type, _default_value)                         \