o5h / themachinery-books

This repository contains the source of "The Machinery book " and some other books.

The Machinery book

⚠ WARNING: This project is currently a work in progress.

This repository contains the source of "The Machinery" book and some other books.

How to contribute?

If you want to contribute to this project please read the CONTRIBUTING.md first!

Requirements

Building the book requires

• mdBook
• mdbook-toc
• mdbook-tera
• mdbook-linkcheck

To get them:

$ cargo install mdbook
$ cargo install mdbook-toc
$ cargo install mdbook-tera
$ cargo install mdbook-linkcheck

Alternatively you can download the latest executables for:

• mdbook
• mdbook-toc
• mdbook-linkcheck

Writing

Edit the markdown files with your editor of choice (we like Typora). If you want to see the changes live, run:

# For the_machinery_book
$ cd the_machinery_book && mdbook serve

# For the tutorials
$ cd tutorials && mdbook serve

If you want to add new pages to the system just add them to SUMMARY.md. As soon as they are in there they will be used for the book.

About Links

If you want to link anything within the book please make use of

• {{base_url}} for the base address of your current book
• {{the_machinery_book}} to cross link to this book
• {{tutorials}} to cross link to this book
• {{docs}} to link to the documentation e.g. {{docs}}plugins/physx/physx_scene.h.html#structtm_physx_scene_api

They will be replaced on build with the correct URL's.

Besides the build process will check all links if they are valid. If not you will not be able to build the game.

Linking to API types

If you want to link to functions or API's you can just write in your markdown:

`tm_physx_scene_api`

On deploy the book will automaically find those terms and replaces them with proper linking.

Working in dropbox paper

In case you have written your article in dropbox paper you can export your work as following:

1. Open your document
2. Open the ᠁ Symbol (Menu)
3. Search for the "Export" point
4. Export as .md file

Open your markdown editor of choice (e.g. Typora) and check if the formatting is correct. If yes copy and paste the file into the correct location in the book. After this open the SUMMARY.md of the corresponding book and add a entry.

To verify everything run: (choose the correct book)

# For the_machinery_book
$ cd the_machinery_book && mdbook serve

# For the tutorials
$ cd tutorials && mdbook serve

Open the in the browser using http://localhost:3000.

If everything works and looks like it supposed to you can commit to master and push.

Working in paper

In case you have written your article in dropbox paper you can export your work as following:

1. Open your document
2. Open the ᠁ Symbol (Menu)
3. Search for the "Export" point
4. Export as .md file

Open your markdown editor of choice (e.g. Typora) and check if the formatting is correct. If yes copy and paste the file into the correct location in the book. After this open the SUMMARY.md of the corresponding book and add a entry.

To verify everything run: (choose the correct book)

# For the_machinery_book
$ cd the_machinery_book && mdbook serve

# For the tutorials
$ cd tutorials && mdbook serve

If everything works commit to master and push.

Building

To build the book, type:

# For the_machinery_book
$ cd the_machinery_book && mdbook build

# For the tutorials
$ cd tutorials && mdbook build

The output will appear in the book subdirectory. To check it out, open it in your web browser:

Firefox:

$ firefox book/index.html                       # Linux
$ open -a "Firefox" book/index.html             # OS X
$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
$ start firefox.exe .\book\index.html           # Windows (Cmd)

Chrome:

$ google-chrome book/index.html                 # Linux
$ open -a "Google Chrome" book/index.html       # OS X
$ Start-Process "chrome.exe" .\book\index.html  # Windows (PowerShell)
$ start chrome.exe .\book\index.html            # Windows (Cmd)

Deploy

Run The workflow under Actions.