diff --git a/.github/workflows/build-and-push.yaml b/.github/workflows/build-and-push.yaml index b257b454..9a29ab9b 100644 --- a/.github/workflows/build-and-push.yaml +++ b/.github/workflows/build-and-push.yaml @@ -1,5 +1,5 @@ name: Build & Push docs -on: +on: push: branches: - master @@ -13,4 +13,5 @@ jobs: - name: Deploy docs uses: mhausenblas/mkdocs-deploy-gh-pages@master env: + ENABLE_PDF_EXPORT: 1 GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/.gitignore b/.gitignore index b657e2e4..334b19ea 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,7 @@ docs/node_modules/ .DS_Store docs/public/ docs/.cache/ + +.venv +public +*.log diff --git a/README.md b/README.md index e4d8fd80..2bf5ef57 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This project represents the body of knowledge around business automation solution implementation and reference architecture and can be considered as a living book, we are writing on a daily basis from the experience gathered with our engagements. -All the content is visible [as a BOOK format here](https://ibm-cloud-architecture.github.io/refarch-dba). +All the content is visible [as a BOOK format here](https://ibm-cloud-architecture.github.io/refarch-dba). The content of this repository is the source of the digital business automation reference architecture in the [IBM Garage architecture center visible here](https://www.ibm.com/cloud/architecture/architectures/dba-architecture). This git repository is maintained on a weekly basis and includes more content not yet formally published to IBM sites. As we are implementing the end to end solution we are updating this main git repository to keep best practices accurate. @@ -13,12 +13,17 @@ The content of this repository is the source of the digital business automation The content of this repository is written with markdown files, packaged with [MkDocs](https://www.mkdocs.org/) and can be built into a book-readable format by MkDocs build processes. 1. Install MkDocs locally following the [official documentation instructions](https://www.mkdocs.org/#installation). +1. Install MkDocs PDF export following [its documentation](https://github.com/zhaoterryy/mkdocs-pdf-export-plugin). 1. Install Material plugin for mkdocs: `pip install mkdocs-material` 2. `git clone https://github.com/ibm-cloud-architecture/refarch-dba` _(or your forked repository if you plan to edit)_ 3. `cd refarch-dba` 4. `mkdocs serve` 5. Go to `http://127.0.0.1:8000/` in your browser. +If you wish to generate PDF files, substitute `EXPORT_PDF_EXPORT=1 mkdocs +serve` for the command above. You can use `EXPORT_PDF_EXPORT=1 mkdocs build` to +create a `public` directory tree that includes the PDF docs for local browsing. + ### Building this booklet locally but with docker In some cases you might not want to alter your Python setup and rather go with a docker image instead. This requires docker is running locally on your computer though. diff --git a/docs/extra.css b/docs/extra.css index 78511490..391a73ef 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -179,4 +179,20 @@ width: 8rem; .md-typeset .admonition { font-size: .75rem; -} \ No newline at end of file +} + +@media print { + @page { + @bottom-right { + content: "Page " counter(page) " of " counter(pages); + } + } + + body > :not(div.md-container) { + display: none; + } + + .md-typeset details { + page-break-inside: auto; + } +} diff --git a/mkdocs.yml b/mkdocs.yml index c7a89721..36be8050 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,8 +25,10 @@ use_directory_urls: true plugins: - search: lang: en + - pdf-export: + enabled_if_env: ENABLE_PDF_EXPORT + - markdown_extensions: - attr_list - admonition @@ -69,7 +71,6 @@ nav: - Overview: technology/index.md - Automation Decision Service: technology/decision/index.md - RPA: technology/rpa/index.md - - title: Use cases - Use Cases: - Accounts Payable: use-cases/accounts-pay/index.md - HR Onboarding App: use-cases/hr-onboard-app/index.md @@ -78,4 +79,4 @@ nav: - Onboarding Automation: use-cases/onboarding-automation/index.md - Shared Services: use-cases/shared-ser/index.md - Connect Salesforce: use-cases/connect-salesforce/index.md - - Contribute: contribute/index.md \ No newline at end of file + - Contribute: contribute/index.md