Implement mdBook to publish docs

- Add book.toml to hold settings for book - Restructure docs folder for mdBook - Remove `help` section from Makefile - Update references to docs location - Add github action to publish docs to gh pages
Igalia · Aug 1, 2023 · 2246276 · 2246276
1 parent ac82376
commit 2246276
Show file tree

Hide file tree

Showing 84 changed files with 77 additions and 31 deletions.
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -0,0 +1,29 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: 'latest'
+
+      - run: cd docs && mdbook build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/book
diff --git a/.gitignore b/.gitignore
@@ -5,8 +5,8 @@
 *~
 \#*\#
 
-#compiled help files
-help/*
+#compiled docs
+docs/book
 
 #release tarballs
 phpreport*.tar.gz

diff --git a/Makefile b/Makefile
@@ -10,33 +10,6 @@ zip: tgz
 	VERSION=`./version.sh`;	\
 	tar tf phpreport_$${VERSION}.tar.gz | zip -@ phpreport_$${VERSION}.zip
 
-help:
-	#create dirs
-	mkdir -p help/user
-	mkdir -p help/admin
-	mkdir -p help/developer
-	#copy images
-	cp -r docs/user/i help/user
-	cp -r docs/developer/i help/developer
-	#generate footer
-	echo -ne '\n.. class:: credits\n\n  This file is part of PhpReport ' > footer
-	VERSION=`./version.sh`;	echo -ne $${VERSION} >> footer
-	echo -e ' documentation.' >> footer
-	echo -ne '  Generated on ' >> footer
-	date >> footer
-	#parse rst
-	for i in `find -name *.rst -not -path "*vendor/*"` ; do \
-	  #rename .rst for .html in links to other doc pages \
-	  sed 's/\.rst/\.html/g' $$i > tmp; \
-	  #append footer \
-	  cat footer >> tmp; \
-	  #extract file name to be used as the output file name \
-	  FILE=`echo $$i | awk '{firstpart=substr($$i, 8);x=index(firstpart,".rst");print substr(firstpart, 1,x)}'`; \
-	  #generate html file \
-	  rst2html tmp help/$${FILE}html; \
-	  done
-	rm tmp
-	rm footer
 
 minify:
 	# WARNING: this will remove any unstaged changes! Do not run on a development directory
@@ -61,5 +34,3 @@ minify:
 	  done
 	rm tmp
 
-#prevent makefile docs are up-to-date
-.PHONY: help
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 [![Test](https://github.com/Igalia/phpreport/actions/workflows/runtests.yml/badge.svg)](https://github.com/Igalia/phpreport/actions/workflows/runtests.yml)
 
+[![Documentation](https://github.com/Igalia/phpreport/actions/workflows/publish-docs.yml/badge.svg)](https://github.com/Igalia/phpreport/actions/workflows/publish-docs.yml)
+
 # PhpReport
 
 PhpReport is a web application for time tracking, which provides useful

diff --git a/book.toml b/book.toml
@@ -0,0 +1,12 @@
+[book]
+authors = ["Igalia"]
+language = "en"
+multilingual = false
+title = "PhpReport Documentation"
+description = "Time tracking and project management"
+src = "docs"
+
+[output.html]
+theme = "theme"
+git-repository-icon = "fa-git"
+git-repository-url = "https://github.com/Igalia/phpreport"
diff --git a/docs/src/README.md b/docs/src/README.md
@@ -0,0 +1,3 @@
+# PhpReport Introduction
+
+> ⚠️ Please note that we are in the process of rewriting PhpReport. We are trying to keep up with updating the documentation, but there may be some pages that remain in flux during the rewrite.
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -0,0 +1,29 @@
+# Summary
+
+[Introduction](README.md)
+
+- [Developer Documentation](./developer/index.md)
+  - [Setting up a development environment](./developer/devel-setup.md)
+  - [Overview](./developer/overview.md)
+  - [Data model](./developer/data-model.md)
+  - [Data access layer](./developer/data-access-layer.md)
+  - [API](./developer/api.md)
+  - [User interface](./developer/user-web-interface.md)
+  - [Business logic layer and plugin system](./developer/business-logic-layer.md)
+  - [Web service layer](./developer/web-service-layer.md)
+- [User Documentation](./user/index.md)
+  - [Overview](./user/overview.md)
+  - [Tasks Management](./user/tasks.md)
+  - [Reports](./user/reports.md)
+  - [Projects Management](./user/projects-management.md)
+  - [User Management](./user/users-management.md)
+  - [Client Management](./user/clients-management.md)
+  - [Cities and work calendars](./user/cities-calendars-management.md)
+  - [Management of Other Entities](./user/other-management.md)
+  - [Application settings](./user/settings-management.md)
+- [Administrator Documentation](./admin/index.md)
+  - [Installation instructions](./admin/installation.md)
+  - [Installing in Docker](./admin/docker.md)
+  - [Upgrade instruction](./admin/upgrade.md)
+  - [How to set up LDAP authentication](./admin/ldap.md)
+  - [Common Problems](./admin/common-problems.md)
diff --git a/docs/admin/common-problems.md → docs/src/admin/common-problems.md b/docs/admin/common-problems.md → docs/src/admin/common-problems.md
diff --git a/docs/admin/docker.md → docs/src/admin/docker.md b/docs/admin/docker.md → docs/src/admin/docker.md
diff --git a/docs/admin/index.md → docs/src/admin/index.md b/docs/admin/index.md → docs/src/admin/index.md
diff --git a/docs/admin/installation.md → docs/src/admin/installation.md b/docs/admin/installation.md → docs/src/admin/installation.md
diff --git a/docs/admin/ldap.md → docs/src/admin/ldap.md b/docs/admin/ldap.md → docs/src/admin/ldap.md
diff --git a/docs/admin/upgrade.md → docs/src/admin/upgrade.md b/docs/admin/upgrade.md → docs/src/admin/upgrade.md
diff --git a/docs/developer/api.md → docs/src/developer/api.md b/docs/developer/api.md → docs/src/developer/api.md
diff --git a/docs/developer/business-logic-layer.md → docs/src/developer/business-logic-layer.md b/docs/developer/business-logic-layer.md → docs/src/developer/business-logic-layer.md
diff --git a/docs/developer/data-access-layer.md → docs/src/developer/data-access-layer.md b/docs/developer/data-access-layer.md → docs/src/developer/data-access-layer.md
diff --git a/docs/developer/data-model.md → docs/src/developer/data-model.md b/docs/developer/data-model.md → docs/src/developer/data-model.md
diff --git a/docs/developer/devel-setup.md → docs/src/developer/devel-setup.md b/docs/developer/devel-setup.md → docs/src/developer/devel-setup.md
diff --git a/docs/developer/i/Action-sequence.png → docs/src/developer/i/Action-sequence.png b/docs/developer/i/Action-sequence.png → docs/src/developer/i/Action-sequence.png
diff --git a/docs/developer/i/Action.png → docs/src/developer/i/Action.png b/docs/developer/i/Action.png → docs/src/developer/i/Action.png
diff --git a/docs/developer/i/BaseDAO.png → docs/src/developer/i/BaseDAO.png b/docs/developer/i/BaseDAO.png → docs/src/developer/i/BaseDAO.png
diff --git a/docs/developer/i/DAOFactory.png → docs/src/developer/i/DAOFactory.png b/docs/developer/i/DAOFactory.png → docs/src/developer/i/DAOFactory.png
diff --git a/docs/developer/i/DAOFactorySequence.png → docs/src/developer/i/DAOFactorySequence.png b/docs/developer/i/DAOFactorySequence.png → docs/src/developer/i/DAOFactorySequence.png
diff --git a/docs/developer/i/E-R-data-model.png → docs/src/developer/i/E-R-data-model.png b/docs/developer/i/E-R-data-model.png → docs/src/developer/i/E-R-data-model.png
diff --git a/docs/developer/i/Facade-and-action.png → docs/src/developer/i/Facade-and-action.png b/docs/developer/i/Facade-and-action.png → docs/src/developer/i/Facade-and-action.png
diff --git a/docs/developer/i/Facades.png → docs/src/developer/i/Facades.png b/docs/developer/i/Facades.png → docs/src/developer/i/Facades.png
diff --git a/docs/developer/i/RelationshipDAO.png → docs/src/developer/i/RelationshipDAO.png b/docs/developer/i/RelationshipDAO.png → docs/src/developer/i/RelationshipDAO.png
diff --git a/docs/developer/i/VO.png → docs/src/developer/i/VO.png b/docs/developer/i/VO.png → docs/src/developer/i/VO.png
diff --git a/docs/developer/i/architecture.png → docs/src/developer/i/architecture.png b/docs/developer/i/architecture.png → docs/src/developer/i/architecture.png
diff --git a/docs/developer/i/servicesSequence.png → docs/src/developer/i/servicesSequence.png b/docs/developer/i/servicesSequence.png → docs/src/developer/i/servicesSequence.png
diff --git a/docs/developer/i/web-login-sequence.png → docs/src/developer/i/web-login-sequence.png b/docs/developer/i/web-login-sequence.png → docs/src/developer/i/web-login-sequence.png
diff --git a/docs/developer/index.md → docs/src/developer/index.md b/docs/developer/index.md → docs/src/developer/index.md
diff --git a/docs/developer/overview.md → docs/src/developer/overview.md b/docs/developer/overview.md → docs/src/developer/overview.md
diff --git a/docs/developer/user-web-interface.md → docs/src/developer/user-web-interface.md b/docs/developer/user-web-interface.md → docs/src/developer/user-web-interface.md
diff --git a/docs/developer/web-service-layer.md → docs/src/developer/web-service-layer.md b/docs/developer/web-service-layer.md → docs/src/developer/web-service-layer.md
diff --git a/docs/user/cities-calendars-management.md → docs/src/user/cities-calendars-management.md b/docs/user/cities-calendars-management.md → docs/src/user/cities-calendars-management.md
diff --git a/docs/user/clients-management.md → docs/src/user/clients-management.md b/docs/user/clients-management.md → docs/src/user/clients-management.md
diff --git a/docs/user/i/acc-hours-screen.png → docs/src/user/i/acc-hours-screen.png b/docs/user/i/acc-hours-screen.png → docs/src/user/i/acc-hours-screen.png
diff --git a/docs/user/i/areas-mgmt-screen.png → docs/src/user/i/areas-mgmt-screen.png b/docs/user/i/areas-mgmt-screen.png → docs/src/user/i/areas-mgmt-screen.png
diff --git a/docs/user/i/calendars-mgmt-screen.png → docs/src/user/i/calendars-mgmt-screen.png b/docs/user/i/calendars-mgmt-screen.png → docs/src/user/i/calendars-mgmt-screen.png
diff --git a/docs/user/i/cities-mgmt-screen.png → docs/src/user/i/cities-mgmt-screen.png b/docs/user/i/cities-mgmt-screen.png → docs/src/user/i/cities-mgmt-screen.png
diff --git a/docs/user/i/client-assignment-subwindow.png → ...rc/user/i/client-assignment-subwindow.png b/docs/user/i/client-assignment-subwindow.png → ...rc/user/i/client-assignment-subwindow.png
diff --git a/docs/user/i/client-inline-editor.png → docs/src/user/i/client-inline-editor.png b/docs/user/i/client-inline-editor.png → docs/src/user/i/client-inline-editor.png
diff --git a/docs/user/i/clients-mgmt-screen.png → docs/src/user/i/clients-mgmt-screen.png b/docs/user/i/clients-mgmt-screen.png → docs/src/user/i/clients-mgmt-screen.png
diff --git a/docs/user/i/compensations-mgmt-screen.png → .../src/user/i/compensations-mgmt-screen.png b/docs/user/i/compensations-mgmt-screen.png → .../src/user/i/compensations-mgmt-screen.png
diff --git a/docs/user/i/cost-classes.png → docs/src/user/i/cost-classes.png b/docs/user/i/cost-classes.png → docs/src/user/i/cost-classes.png
diff --git a/docs/user/i/main-classes.png → docs/src/user/i/main-classes.png b/docs/user/i/main-classes.png → docs/src/user/i/main-classes.png
diff --git a/docs/user/i/menu-data-mgmt-areas.png → docs/src/user/i/menu-data-mgmt-areas.png b/docs/user/i/menu-data-mgmt-areas.png → docs/src/user/i/menu-data-mgmt-areas.png
diff --git a/docs/user/i/menu-data-mgmt-calendars.png → docs/src/user/i/menu-data-mgmt-calendars.png b/docs/user/i/menu-data-mgmt-calendars.png → docs/src/user/i/menu-data-mgmt-calendars.png
diff --git a/docs/user/i/menu-data-mgmt-cities.png → docs/src/user/i/menu-data-mgmt-cities.png b/docs/user/i/menu-data-mgmt-cities.png → docs/src/user/i/menu-data-mgmt-cities.png
diff --git a/docs/user/i/menu-data-mgmt-clients.png → docs/src/user/i/menu-data-mgmt-clients.png b/docs/user/i/menu-data-mgmt-clients.png → docs/src/user/i/menu-data-mgmt-clients.png
diff --git a/docs/user/i/menu-data-mgmt-compensations.png → ...c/user/i/menu-data-mgmt-compensations.png b/docs/user/i/menu-data-mgmt-compensations.png → ...c/user/i/menu-data-mgmt-compensations.png
diff --git a/docs/user/i/menu-data-mgmt-projects.png → docs/src/user/i/menu-data-mgmt-projects.png b/docs/user/i/menu-data-mgmt-projects.png → docs/src/user/i/menu-data-mgmt-projects.png
diff --git a/docs/user/i/menu-data-mgmt-settings.png → docs/src/user/i/menu-data-mgmt-settings.png b/docs/user/i/menu-data-mgmt-settings.png → docs/src/user/i/menu-data-mgmt-settings.png
diff --git a/docs/user/i/menu-data-mgmt-users.png → docs/src/user/i/menu-data-mgmt-users.png b/docs/user/i/menu-data-mgmt-users.png → docs/src/user/i/menu-data-mgmt-users.png
diff --git a/docs/user/i/project-details-screen.png → docs/src/user/i/project-details-screen.png b/docs/user/i/project-details-screen.png → docs/src/user/i/project-details-screen.png
diff --git a/docs/user/i/project-edition-window.png → docs/src/user/i/project-edition-window.png b/docs/user/i/project-edition-window.png → docs/src/user/i/project-edition-window.png
diff --git a/docs/user/i/project-evaluation-screen.png → .../src/user/i/project-evaluation-screen.png b/docs/user/i/project-evaluation-screen.png → .../src/user/i/project-evaluation-screen.png
diff --git a/docs/user/i/project-summary-screen.png → docs/src/user/i/project-summary-screen.png b/docs/user/i/project-summary-screen.png → docs/src/user/i/project-summary-screen.png
diff --git a/docs/user/i/projects-mgmt-screen.png → docs/src/user/i/projects-mgmt-screen.png b/docs/user/i/projects-mgmt-screen.png → docs/src/user/i/projects-mgmt-screen.png
diff --git a/docs/user/i/reports-menu.png → docs/src/user/i/reports-menu.png b/docs/user/i/reports-menu.png → docs/src/user/i/reports-menu.png
diff --git a/docs/user/i/settings-mgmt-screen.png → docs/src/user/i/settings-mgmt-screen.png b/docs/user/i/settings-mgmt-screen.png → docs/src/user/i/settings-mgmt-screen.png
diff --git a/docs/user/i/structure-classes.png → docs/src/user/i/structure-classes.png b/docs/user/i/structure-classes.png → docs/src/user/i/structure-classes.png
diff --git a/docs/user/i/tasks-menu.png → docs/src/user/i/tasks-menu.png b/docs/user/i/tasks-menu.png → docs/src/user/i/tasks-menu.png
diff --git a/docs/user/i/tasks-screen.png → docs/src/user/i/tasks-screen.png b/docs/user/i/tasks-screen.png → docs/src/user/i/tasks-screen.png
diff --git a/docs/user/i/user-assignment-subwindow.png → .../src/user/i/user-assignment-subwindow.png b/docs/user/i/user-assignment-subwindow.png → .../src/user/i/user-assignment-subwindow.png
diff --git a/docs/user/i/user-details-screen.png → docs/src/user/i/user-details-screen.png b/docs/user/i/user-details-screen.png → docs/src/user/i/user-details-screen.png
diff --git a/docs/user/i/user-evaluation-screen.png → docs/src/user/i/user-evaluation-screen.png b/docs/user/i/user-evaluation-screen.png → docs/src/user/i/user-evaluation-screen.png
diff --git a/docs/user/i/user-inline-editor.png → docs/src/user/i/user-inline-editor.png b/docs/user/i/user-inline-editor.png → docs/src/user/i/user-inline-editor.png
diff --git a/docs/user/i/user-tasks-screen.png → docs/src/user/i/user-tasks-screen.png b/docs/user/i/user-tasks-screen.png → docs/src/user/i/user-tasks-screen.png
diff --git a/docs/user/i/users-mgmt-area.png → docs/src/user/i/users-mgmt-area.png b/docs/user/i/users-mgmt-area.png → docs/src/user/i/users-mgmt-area.png
diff --git a/docs/user/i/users-mgmt-city.png → docs/src/user/i/users-mgmt-city.png b/docs/user/i/users-mgmt-city.png → docs/src/user/i/users-mgmt-city.png
diff --git a/docs/user/i/users-mgmt-hour-cost.png → docs/src/user/i/users-mgmt-hour-cost.png b/docs/user/i/users-mgmt-hour-cost.png → docs/src/user/i/users-mgmt-hour-cost.png
diff --git a/docs/user/i/users-mgmt-journey.png → docs/src/user/i/users-mgmt-journey.png b/docs/user/i/users-mgmt-journey.png → docs/src/user/i/users-mgmt-journey.png
diff --git a/docs/user/i/users-mgmt-screen.png → docs/src/user/i/users-mgmt-screen.png b/docs/user/i/users-mgmt-screen.png → docs/src/user/i/users-mgmt-screen.png
diff --git a/docs/user/i/working-day-classes.png → docs/src/user/i/working-day-classes.png b/docs/user/i/working-day-classes.png → docs/src/user/i/working-day-classes.png
diff --git a/docs/user/index.md → docs/src/user/index.md b/docs/user/index.md → docs/src/user/index.md
diff --git a/docs/user/other-management.md → docs/src/user/other-management.md b/docs/user/other-management.md → docs/src/user/other-management.md
diff --git a/docs/user/overview.md → docs/src/user/overview.md b/docs/user/overview.md → docs/src/user/overview.md
diff --git a/docs/user/projects-management.md → docs/src/user/projects-management.md b/docs/user/projects-management.md → docs/src/user/projects-management.md
diff --git a/docs/user/reports.md → docs/src/user/reports.md b/docs/user/reports.md → docs/src/user/reports.md
diff --git a/docs/user/settings-management.md → docs/src/user/settings-management.md b/docs/user/settings-management.md → docs/src/user/settings-management.md
diff --git a/docs/user/tasks.md → docs/src/user/tasks.md b/docs/user/tasks.md → docs/src/user/tasks.md
diff --git a/docs/user/users-management.md → docs/src/user/users-management.md b/docs/user/users-management.md → docs/src/user/users-management.md