docs: split User Guide

stnolting · Jun 2, 2021 · b033d32 · b033d32
1 parent 2723525
commit b033d32
Show file tree

Hide file tree

Showing 39 changed files with 152 additions and 67 deletions.
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -46,22 +46,14 @@ jobs:
       with:
         fetch-depth: 0
 
-    - name: '📚 Build Datasheet (PDF and HTML)'
+    - name: '📚 Build Datasheet and User Guide (PDF and HTML)'
       run: make container
 
-    - name: '📤 Upload Artifact: PDF'
-      uses: actions/upload-artifact@v2
-      with:
-        name: NEORV32-PDF
-        path: docs/NEORV32.pdf
-
     - name: '📤 Upload Artifact: HTML'
       uses: actions/upload-artifact@v2
       with:
-        name: NEORV32-HTML
-        path: |
-          docs/index.html
-          docs/figures
+        name: NEORV32
+        path: docs/public
 
 
   deploy:
@@ -82,11 +74,13 @@ jobs:
 
     - name: '🛠️ Organise public subdir and create a tarball'
       run: |
-        mv NEORV32-HTML public
+        mv NEORV32 public
+        mv public/pdf ./
         mv NEORV32-Doxygen public/sw
         tar zvcf NEORV32-SITE-nightly.tar.gz -C public .
-        mv NEORV32-PDF/NEORV32.pdf public
-        cp public/NEORV32.pdf NEORV32-nightly.pdf
+        cd pdf
+        mv NEORV32.pdf NEORV32-nightly.pdf
+        mv NEORV32_UserGuide.pdf NEORV32_UserGuide-nightly.pdf
 
     # Tagged: create a pre-release or a release (semver)
     # Untagged: update the assets of pre-release 'nightly'
@@ -97,7 +91,7 @@ jobs:
         tag: 'nightly'
         files: |
           NEORV32-SITE-nightly.tar.gz
-          NEORV32-nightly.pdf
+          pdf/NEORV32*nightly.pdf
 
     - name: '🚀 Deploy to GitHub-Pages'
       run: |

diff --git a/.gitignore b/.gitignore
@@ -18,10 +18,9 @@ sw/image_gen/image_gen.exe
 ~*
 
 # no generated documentation stuff
-docs/doxygen_build
-docs/NEORV32.pdf
-/docs/.asciidoctor
-/docs/index.html
+/docs/doxygen_build/
+/docs/.asciidoctor/
+/docs/public/
 
 # no compiled ghdl stuff
 *.cf
diff --git a/Makefile b/Makefile
@@ -1,23 +1,46 @@
 .DEFAULT_GOAL := help
 
+all: pdf html ug-pdf ug-html
+	mkdir -p docs/public/img/
+	cp -vr docs/figures/* docs/public/img/
+
 # Generate PDF datasheet
 pdf:
 	cd docs; \
 	[ -f revnumber.txt ] && REVNUMBER='-a revnumber='"$$(cat revnumber.txt)" || unset REVNUMBER; \
 	asciidoctor-pdf $$REVNUMBER \
-	  -a pdf-theme=src_adoc/neorv32-theme.yml \
+	  -a pdf-theme=neorv32-theme.yml \
 	  -r asciidoctor-diagram \
-	  src_adoc/neorv32.adoc \
-	  --out-file NEORV32.pdf
+	  datasheet/main.adoc \
+	  --out-file public/pdf/NEORV32.pdf
 
 # Generate HTML datasheet
 html:
 	cd docs; \
 	[ -f revnumber.txt ] && REVNUMBER='-a revnumber='"$$(cat revnumber.txt)" || unset REVNUMBER; \
 	asciidoctor $$REVNUMBER \
 	  -r asciidoctor-diagram \
-	  src_adoc/index.adoc \
-	  --out-file index.html
+	  datasheet/index.adoc \
+	  --out-file public/index.html
+
+# Generate PDF user guide
+ug-pdf:
+	cd docs; \
+	[ -f revnumber.txt ] && REVNUMBER='-a revnumber='"$$(cat revnumber.txt)" || unset REVNUMBER; \
+	asciidoctor-pdf $$REVNUMBER \
+	  -a pdf-theme=neorv32-theme.yml \
+	  -r asciidoctor-diagram \
+	  userguide/main.adoc \
+	  --out-file public/pdf/NEORV32_UserGuide.pdf
+
+# Generate HTML user guide
+ug-html:
+	cd docs; \
+	[ -f revnumber.txt ] && REVNUMBER='-a revnumber='"$$(cat revnumber.txt)" || unset REVNUMBER; \
+	asciidoctor $$REVNUMBER \
+	  -r asciidoctor-diagram \
+	  userguide/index.adoc \
+	  --out-file public/ug/index.html
 
 # Generate revnumber.txt for overriding the revnumber attribute in 'pdf' and/or 'html'
 revnumber:
@@ -27,11 +50,13 @@ revnumber:
 
 # Build 'pdf' and 'html' in an 'asciidoctor-wavedrom' container
 container: revnumber
-	docker run --rm -v /$(PWD)://documents/ btdi/asciidoctor make pdf html
+	docker run --rm -v /$(PWD)://documents/ btdi/asciidoctor make all
 
 # Help
 help:
 	@echo "Targets:"
-	@echo " help - show this text"
-	@echo " html - build project documentation as HTML page (docs/index.html)"
-	@echo " pdf  - build project documentation as pdf file (docs/NEORV32.pdf)"
+	@echo " help    - show this text"
+	@echo " pdf     - build datasheet as pdf file (docs/public/pdf/NEORV32.pdf)"
+	@echo " html    - build datasheet as HTML page (docs/public/index.html)"
+	@echo " ug-pdf  - build user guide as pdf file (docs/public/pdf/NEORV32_UserGuide.pdf)"
+	@echo " ug-html - build user guide as HTML page (docs/public/ug/index.html)"
diff --git a/README.md b/README.md
@@ -11,7 +11,9 @@
 [![license](https://img.shields.io/github/license/stnolting/neorv32?longCache=true&style=flat-square)](https://github.com/stnolting/neorv32/blob/master/LICENSE)
 [![release](https://img.shields.io/github/v/release/stnolting/neorv32?longCache=true&style=flat-square&logo=GitHub)](https://github.com/stnolting/neorv32/releases)
 [![datasheet (pdf)](https://img.shields.io/badge/data%20sheet-PDF-ffbd00?longCache=true&style=flat-square&logo=asciidoctor)](https://github.com/stnolting/neorv32/releases/tag/nightly)
-[![datasheet (html)](https://img.shields.io/badge/data%20sheet-HTML-ffbd00?longCache=true&style=flat-square&logo=asciidoctor)](https://stnolting.github.io/neorv32)
+[![datasheet (html)](https://img.shields.io/badge/-HTML-ffbd00?longCache=true&style=flat-square)](https://stnolting.github.io/neorv32)
+[![userguide (pdf)](https://img.shields.io/badge/user%20guide-PDF-ffbd00?longCache=true&style=flat-square&logo=asciidoctor)](https://github.com/stnolting/neorv32/releases/tag/nightly)
+[![userguide (html)](https://img.shields.io/badge/-HTML-ffbd00?longCache=true&style=flat-square)](https://stnolting.github.io/neorv32/ug)
 [![doxygen](https://img.shields.io/badge/doxygen-HTML-ffbd00?longCache=true&style=flat-square&logo=Doxygen)](https://stnolting.github.io/neorv32/sw/files.html)
 
 * [Overview](#Overview)

diff --git a/docs/src_adoc/content.adoc → docs/datasheet/content.adoc b/docs/src_adoc/content.adoc → docs/datasheet/content.adoc
@@ -11,6 +11,4 @@ include::software.adoc[]
 
 include::on_chip_debugger.adoc[]
 
-include::getting_started.adoc[]
-
-include::legal.adoc[]
+include::../legal.adoc[]
diff --git a/docs/src_adoc/cpu.adoc → docs/datasheet/cpu.adoc b/docs/src_adoc/cpu.adoc → docs/datasheet/cpu.adoc
diff --git a/docs/src_adoc/cpu_csr.adoc → docs/datasheet/cpu_csr.adoc b/docs/src_adoc/cpu_csr.adoc → docs/datasheet/cpu_csr.adoc
diff --git a/docs/src_adoc/index.adoc → docs/datasheet/index.adoc b/docs/src_adoc/index.adoc → docs/datasheet/index.adoc
@@ -1,19 +1,20 @@
-= The NEORV32 RISC-V Processor
+= The NEORV32 RISC-V Processor: Datasheet
+:title: [Datasheet] The NEORV32 RISC-V Processor
 :author: Dipl.-Ing. Stephan Nolting
 :email: [email protected]
 :description: A size-optimized, customizable and open-source full-scale 32-bit RISC-V soft-core CPU and SoC written in platform-independent VHDL.
 :revnumber: v1.5.6.0
 :doctype: book
 :sectnums:
 :icons: font
-:imagesdir: figures
+:imagesdir: img
 :stem:
 :reproducible:
 :listing-caption: Listing
 :toc: left
 :toclevels: 4
 :title-logo-image: neorv32_logo_dark.png[pdfwidth=6.25in,align=center]
-:favicon: figures/icon.png
+:favicon: img/icon.png
 
 image::neorv32_logo_transparent.png[align=center]
 
@@ -23,6 +24,8 @@ image::riscv_logo.png[width=350,align=center]
 https://github.com/stnolting/neorv32[image:https://img.shields.io/badge/GitHub-stnolting%2Fneorv32-ffbd00?style=flat-square&logo=github&[title='homepage']]
 https://github.com/stnolting/neorv32/blob/master/LICENSE[image:https://img.shields.io/github/license/stnolting/neorv32?longCache=true&style=flat-square[title='license']]
 https://github.com/stnolting/neorv32/releases/tag/nightly[image:https://img.shields.io/badge/data%20sheet-PDF-ffbd00?longCache=true&style=flat-square&logo=asciidoctor[title='datasheet (pdf)']]
+https://github.com/stnolting/neorv32/releases/tag/nightly[image:https://img.shields.io/badge/user%20guide-PDF-ffbd00?longCache=true&style=flat-square&logo=asciidoctor[title='userguide (pdf)']]
+https://stnolting.github.io/neorv32/ug[image:https://img.shields.io/badge/-HTML-ffbd00?longCache=true&style=flat-square[title='userguide (html)']]
 https://stnolting.github.io/neorv32/sw/files.html[image:https://img.shields.io/badge/doxygen-HTML-ffbd00?longCache=true&style=flat-square&logo=Doxygen[title='doxygen']]
 
 

diff --git a/docs/src_adoc/neorv32.adoc → docs/datasheet/main.adoc b/docs/src_adoc/neorv32.adoc → docs/datasheet/main.adoc
@@ -1,21 +1,19 @@
-= The NEORV32 RISC-V Processor
+= The NEORV32 RISC-V Processor: Datasheet
 :author: Dipl.-Ing. Stephan Nolting
 :email: [email protected]
 :description: A size-optimized, customizable and open-source full-scale 32-bit RISC-V soft-core CPU and SoC written in platform-independent VHDL.
 :revnumber: v1.5.6.0
 :doctype: book
 :sectnums:
 :icons: image
-:iconsdir: icons
+:iconsdir: ../icons
 :imagesdir: ../figures
 :stem:
 :reproducible:
 :listing-caption: Listing
 :toc: macro
 :toclevels: 4
 :title-logo-image: image:neorv32_logo_dark.png[pdfwidth=6.25in,align=center]
-// Uncomment next line to add a title page (or set doctype to book)
-//:title-page:
 // Uncomment next line to set page size (default is A4)
 //:pdf-page-size: Letter
 

diff --git a/docs/src_adoc/on_chip_debugger.adoc → docs/datasheet/on_chip_debugger.adoc b/docs/src_adoc/on_chip_debugger.adoc → docs/datasheet/on_chip_debugger.adoc
diff --git a/docs/src_adoc/overview.adoc → docs/datasheet/overview.adoc b/docs/src_adoc/overview.adoc → docs/datasheet/overview.adoc
diff --git a/docs/src_adoc/soc.adoc → docs/datasheet/soc.adoc b/docs/src_adoc/soc.adoc → docs/datasheet/soc.adoc
diff --git a/docs/src_adoc/soc_bootrom.adoc → docs/datasheet/soc_bootrom.adoc b/docs/src_adoc/soc_bootrom.adoc → docs/datasheet/soc_bootrom.adoc
diff --git a/docs/src_adoc/soc_cfs.adoc → docs/datasheet/soc_cfs.adoc b/docs/src_adoc/soc_cfs.adoc → docs/datasheet/soc_cfs.adoc
diff --git a/docs/src_adoc/soc_dmem.adoc → docs/datasheet/soc_dmem.adoc b/docs/src_adoc/soc_dmem.adoc → docs/datasheet/soc_dmem.adoc
diff --git a/docs/src_adoc/soc_gpio.adoc → docs/datasheet/soc_gpio.adoc b/docs/src_adoc/soc_gpio.adoc → docs/datasheet/soc_gpio.adoc
diff --git a/docs/src_adoc/soc_icache.adoc → docs/datasheet/soc_icache.adoc b/docs/src_adoc/soc_icache.adoc → docs/datasheet/soc_icache.adoc
diff --git a/docs/src_adoc/soc_imem.adoc → docs/datasheet/soc_imem.adoc b/docs/src_adoc/soc_imem.adoc → docs/datasheet/soc_imem.adoc
diff --git a/docs/src_adoc/soc_mtime.adoc → docs/datasheet/soc_mtime.adoc b/docs/src_adoc/soc_mtime.adoc → docs/datasheet/soc_mtime.adoc
diff --git a/docs/src_adoc/soc_nco.adoc → docs/datasheet/soc_nco.adoc b/docs/src_adoc/soc_nco.adoc → docs/datasheet/soc_nco.adoc
diff --git a/docs/src_adoc/soc_neoled.adoc → docs/datasheet/soc_neoled.adoc b/docs/src_adoc/soc_neoled.adoc → docs/datasheet/soc_neoled.adoc
diff --git a/docs/src_adoc/soc_pwm.adoc → docs/datasheet/soc_pwm.adoc b/docs/src_adoc/soc_pwm.adoc → docs/datasheet/soc_pwm.adoc
diff --git a/docs/src_adoc/soc_spi.adoc → docs/datasheet/soc_spi.adoc b/docs/src_adoc/soc_spi.adoc → docs/datasheet/soc_spi.adoc
diff --git a/docs/src_adoc/soc_sysinfo.adoc → docs/datasheet/soc_sysinfo.adoc b/docs/src_adoc/soc_sysinfo.adoc → docs/datasheet/soc_sysinfo.adoc
diff --git a/docs/src_adoc/soc_trng.adoc → docs/datasheet/soc_trng.adoc b/docs/src_adoc/soc_trng.adoc → docs/datasheet/soc_trng.adoc
diff --git a/docs/src_adoc/soc_twi.adoc → docs/datasheet/soc_twi.adoc b/docs/src_adoc/soc_twi.adoc → docs/datasheet/soc_twi.adoc
diff --git a/docs/src_adoc/soc_uart.adoc → docs/datasheet/soc_uart.adoc b/docs/src_adoc/soc_uart.adoc → docs/datasheet/soc_uart.adoc
diff --git a/docs/src_adoc/soc_wdt.adoc → docs/datasheet/soc_wdt.adoc b/docs/src_adoc/soc_wdt.adoc → docs/datasheet/soc_wdt.adoc
diff --git a/docs/src_adoc/soc_wishbone.adoc → docs/datasheet/soc_wishbone.adoc b/docs/src_adoc/soc_wishbone.adoc → docs/datasheet/soc_wishbone.adoc
diff --git a/docs/src_adoc/software.adoc → docs/datasheet/software.adoc b/docs/src_adoc/software.adoc → docs/datasheet/software.adoc
diff --git a/docs/src_adoc/icons/important.png → docs/icons/important.png b/docs/src_adoc/icons/important.png → docs/icons/important.png
diff --git a/docs/src_adoc/icons/note.png → docs/icons/note.png b/docs/src_adoc/icons/note.png → docs/icons/note.png
diff --git a/docs/src_adoc/icons/tip.png → docs/icons/tip.png b/docs/src_adoc/icons/tip.png → docs/icons/tip.png
diff --git a/docs/src_adoc/icons/warning.png → docs/icons/warning.png b/docs/src_adoc/icons/warning.png → docs/icons/warning.png
diff --git a/docs/src_adoc/legal.adoc → docs/legal.adoc b/docs/src_adoc/legal.adoc → docs/legal.adoc
diff --git a/docs/src_adoc/neorv32-theme.yml → docs/neorv32-theme.yml b/docs/src_adoc/neorv32-theme.yml → docs/neorv32-theme.yml