From db90c933fac47afddec4d64d6e882acf7fb124ca Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 21 May 2023 11:17:32 -0500 Subject: [PATCH] Add images to generated documentation Convert from dia to inkscape. Drop a symlink to the image dir into each of the sphinx source directories since sphinx urls are rooted at the sphinx source directory. --- .gitignore | 3 + Makefile | 54 +- doc/diagrams/key.svg | 1257 ++++++++++++++++++++++++++++++++++++ doc/include/macros.m4 | 19 +- doc/src/er_diagrams/key.m4 | 9 +- 5 files changed, 1309 insertions(+), 33 deletions(-) create mode 100644 doc/diagrams/key.svg diff --git a/.gitignore b/.gitignore index 66b9fd2..0710d1b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# Built image files +doc/images/ + # Built documentation doc/sphinx-doc/ diff --git a/Makefile b/Makefile index db3d19d..e13c8ce 100644 --- a/Makefile +++ b/Makefile @@ -99,7 +99,9 @@ SPHINX_BUILT_HTML_SINGLE := $(SPHINX_BUILDDIR)/$(HTML_SINGLE_TARGET) STOCK_SRCDIR := $(PREFIX)/src HTML_STATIC_DIR := $(PREFIX)/_static HTML_SRCDIR := $(SPHINX_PREFIX)/$(HTML_SRCDIR) +HTML_IMAGEDIR := $(HTML_SRCDIR)/images LATEX_SRCDIR := $(SPHINX_PREFIX)/latex_src +LATEX_IMAGEDIR := $(LATEX_SRCDIR)/images # Locations of m4 macros M4_INCLUDE_PATH := include @@ -158,13 +160,13 @@ SPHINX_PDF_A4_TARGET := $(SPHINX_BUILT_LATEX_A4)/$(PDF_NAME) SPHINX_PDF_LETTER_TARGET := $(SPHINX_BUILT_LATEX_LETTER)/$(PDF_NAME) # Image targets -DIA_BASEDIR := diagrams/dia/ -IMAGES_BASEDIR := images/ -DIA_FILES := $(wildcard $(DIA_BASEDIR)*.dia) +INKSCAPE_BASEDIR := $(PREFIX)/diagrams/ +IMAGES_BASEDIR := $(PREFIX)/images/ +INKSCAPE_FILES := $(wildcard $(INKSCAPE_BASEDIR)*.svg) -PARTIAL_PATHS := $(subst $(DIA_BASEDIR),$(IMAGES_BASEDIR), $(DIA_FILES)) -SVG_FILES := $(patsubst %.dia,%.svg,$(PARTIAL_PATHS)) -PNG_FILES := $(patsubst %.dia,%.png,$(PARTIAL_PATHS)) +PARTIAL_PATHS := $(subst $(INKSCAPE_BASEDIR),$(IMAGES_BASEDIR), $(INKSCAPE_FILES)) +SVG_FILES := $(patsubst %.svg,%.svg,$(PARTIAL_PATHS)) +PNG_FILES := $(patsubst %.svg,%.png,$(PARTIAL_PATHS)) ifdef LOCALHTML HTML_IMAGE_FILES := $(PNG_FILES) @@ -176,11 +178,12 @@ CLEAN_TARGETS := $(PREFIX)/requirements.txt.new \ $(SPHINX_PREFIX) \ $(HTML_RST_FILES) $(LATEX_RST_FILES) \ $(SVG_FILES) $(PNG_FILES) \ - $(PDF_A4_TARGET) $(PDF_LETTER_TARGET) + $(PDF_A4_TARGET) $(PDF_LETTER_TARGET) \ + $(IMAGES_BASEDIR) # Prerequsites for html generation HTML_PREREQS := install-sphinx html_rst $(HTML_IMAGE_FILES) $(HTML_EPILOG) \ - $(HTML_STATIC_DIR) + $(HTML_STATIC_DIR) $(HTML_IMAGEDIR) ## ## The available targets for make (make TARGET) are: @@ -319,11 +322,11 @@ latex_rst: $(LATEX_DIRS) $(LATEX_RST_FILES) $(LATEX_SRCDIR) ## png_files Build *.png files from dia source .PHONY: png_files -png_files: $(PNG_FILES) +png_files: $(IMAGES_BASEDIR) $(PNG_FILES) ## svg_files Build *.svg files from dia source .PHONY: svg_files -svg_files: $(SVG_FILES) +svg_files: $(IMAGES_BASEDIR) $(SVG_FILES) # # Internal targets @@ -346,9 +349,18 @@ $(PDF_LETTER_PATH): $(PDF_LETTER_TARGET) # Construct all the source dirs used to build output $(LATEX_DIRS) $(HTML_DIRS) $(HTML_SRCDIR) $(LATEX_SRCDIR) \ - $(HTML_STATIC_DIR) $(DOC_ROOT): + $(HTML_STATIC_DIR) $(DOC_ROOT) $(IMAGES_BASEDIR): mkdir -p $@ +# Sphinx requires all images be located in the $(SPHINX_PREFIX), +# at least if the paths are not relative to the source RST file and +# we don't want relative paths. So symlink the image dir into +# the sphinx-doc dir. +$(HTML_IMAGEDIR): + ln -s ../../images $(HTML_IMAGEDIR) +$(LATEX_IMAGEDIR): + ln -s ../../images $(LATEX_IMAGEDIR) + # # The files sphinx builds for a pdf # It is unclear whether it's a good idea to run latexmk ourselves @@ -358,14 +370,16 @@ $(LATEX_DIRS) $(HTML_DIRS) $(HTML_SRCDIR) $(LATEX_SRCDIR) \ # # A4 pdf -$(SPHINX_PDF_A4_TARGET): latex_rst $(PNG_FILES) $(LATEX_EPILOG) +$(SPHINX_PDF_A4_TARGET): latex_rst $(PNG_FILES) $(LATEX_EPILOG) \ + $(LATEX_IMAGEDIR) $(SPHINXBUILD) -t a4paper -t latex_epilog -b latex \ $(LATEX_SRCDIR) $(SPHINX_BUILT_LATEX_A4) cd $(SPHINX_BUILT_LATEX_A4) \ && latexmk -pdf -dvi- -ps- $(patsubst %.pdf,%.tex,$(PDF_NAME)) # Letter pdf -$(SPHINX_PDF_LETTER_TARGET): latex_rst $(PNG_FILES) $(LATEX_EPILOG) +$(SPHINX_PDF_LETTER_TARGET): latex_rst $(PNG_FILES) $(LATEX_EPILOG) \ + $(LATEX_IMAGEDIR) $(SPHINXBUILD) -t a4paper -t latex_epilog -b latex \ $(LATEX_SRCDIR) $(SPHINX_BUILT_LATEX_LETTER) cd $(SPHINX_BUILT_LATEX_LETTER) \ @@ -390,16 +404,16 @@ $(LATEX_EPILOG): $(SOURCE_EPILOG) $(DOC_DEPENDS) .SECONDEXPANSION: # Construct *.png files -$(SVG_FILES): $$(patsubst %.svg,%.dia,\ - $$(subst $(IMAGES_BASEDIR),$(DIA_BASEDIR),$$@)) \ +$(SVG_FILES): $$(patsubst %.svg,%.svg,\ + $$(subst $(IMAGES_BASEDIR),$(INKSCAPE_BASEDIR),$$@))\ $(DOC_DEPENDS) - dia --export $@ $< + inkscape --export-filename=$@ --export-plain-svg $< # Construct *.png files -$(PNG_FILES): $$(patsubst %.png,%.dia,\ - $$(subst $(IMAGES_BASEDIR),$(DIA_BASEDIR),$$@)) \ +$(PNG_FILES): $$(patsubst %.png,%.svg,\ + $$(subst $(IMAGES_BASEDIR),$(INKSCAPE_BASEDIR),$$@))\ $(DOC_DEPENDS) - dia --export $@ $< + inkscape --export-filename=$@ $< # Build all the RST for html output $(HTML_RST_FILES): $$(patsubst %.rst,%.m4,\ @@ -415,7 +429,7 @@ $(LATEX_RST_FILES): $$(patsubst %.rst,%.m4,\ $$(subst $(LATEX_SRCDIR),$(STOCK_SRCDIR),$$@)) \ $(DOC_DEPENDS) m4 -I $(M4_DOC_INCLUDE_PATH) \ - --define=gdb_output_fmt=latex \ + --define=sdb_output_fmt=latex \ $(patsubst %.rst,%.m4,\ $(subst $(LATEX_SRCDIR),$(STOCK_SRCDIR),$@)) \ > $@ diff --git a/doc/diagrams/key.svg b/doc/diagrams/key.svg new file mode 100644 index 0000000..5732081 --- /dev/null +++ b/doc/diagrams/key.svg @@ -0,0 +1,1257 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + One-to-one + One-to-many + One-to-zero-or-one + One-to-zero-or-more + + + + + + + + + + TABLE_NAME + Column_Name + Column_Name + + + + + + TABLE NAME + Column Names + + + + Relationship Key + Visual Key + + + + + + + + + + Relationship betweencolumns of two tables + + + diff --git a/doc/include/macros.m4 b/doc/include/macros.m4 index 82766fb..c1cf3ce 100644 --- a/doc/include/macros.m4 +++ b/doc/include/macros.m4 @@ -58,21 +58,26 @@ define(`sdb_if_htmlout', dnl Use a macro to transform image paths since this is "easier". -dnl Transform a path to an image so that it is suitable for html output -define(`sdb_html_er_image_path', `../../$1.sdb_html_image_extension') +dnl Transform a path to an image so that it is suitable for html website +dnl output. +define(`sdb_html_er_image_path', `/$1.sdb_html_image_extension') + +dnl Transform a path to an image so that it is suitable for html file: URL +dnl output +define(`sdb_html_file_er_image_path', `/$1.sdb_html_image_extension') dnl Transform a path to an image so that it is suitable for latex output -define(`sdb_latex_er_image_path', `../../$1.sdb_latex_image_extension') +define(`sdb_latex_er_image_path', `/$1.sdb_latex_image_extension') dnl sdb_output_fmt dnl This is dynamically defined when building to control output ifelse(sdb_output_fmt, `latex', - `define(`sdb_er_image_path', `sdb_latex_er_image_path')', + `define(`sdb_er_image_path', `sdb_latex_er_image_path($1)')', sdb_output_fmt, `localhtml', - `define(`sdb_er_image_path', `sdb_latex_er_image_path')', - `define(`sdb_er_image_path', `sdb_html_er_image_path')') + `define(`sdb_er_image_path', `sdb_html_file_er_image_path($1)')', + `define(`sdb_er_image_path', `sdb_html_er_image_path($1)')') -dnl sdb_image_path +dnl sdb_er_image_path dnl This is dynamically defined when building to be one of the 2 macros above. diff --git a/doc/src/er_diagrams/key.m4 b/doc/src/er_diagrams/key.m4 index dd269e0..43c595f 100644 --- a/doc/src/er_diagrams/key.m4 +++ b/doc/src/er_diagrams/key.m4 @@ -23,10 +23,7 @@ sdb_generated_rst() Key --- -.. Commented out figure - .. figure:: sdb_er_image_path()(images/diagram_key) - :alt: Key to symbols used on the entity relationship diagrams +.. figure:: sdb_er_image_path(images/key) + :alt: Key to symbols used on the entity relationship diagrams - Key to the Entity Relationship Diagrams - -The system is not yet displaying images in the docs. + Key to the Entity Relationship Diagrams -- 2.34.1