openra / book Goto Github PK

macOS users will need to build mdbook via cargo (see https://github.com/rust-lang-nursery/mdBook#installation "From Crates.io") as mdbook doesn't provide macOS binaries.

https://github.com/OpenRA/OpenRA/pull/16531/files#diff-d040ed0daafa0ce1819a4eed21cb0f09

Following the "real-world example in chapter 2" link at https://www.openra.net/book/glossary.html#actor yields a 404.

We should educate modders about terrain types which, in general, is a way of restricting locomotion and structure placement to certain cells.

For example in RA naval units can travel over ocean/sea tiles but not rivers.

ref: https://discordapp.com/channels/153649279762694144/160191522053160960/583763827347423241

PRs should not be merged if Travis-CI fails to build the PR.

Related Tickets

#1 - Publish book to GitHub Pages via Travis CI
#2 - Create a GitHub Personal Access Token and add it to Travis repository settings as GITHUB_TOKEN

Why

This will make the book accessible as part of openra.net instead of github.io which, in my opinion, signals that it is officially part of the OpenRA project.

Ticket Author's Personal Opinion

I believe https://docs.openra.net/book would be best because we can put other docs (such as how-tos, trait docs, who knows what we'll have in the future) under https://docs.openra.net/ for consistency.

https://docs.openra.net/ could be an index of sorts for OpenRA documentation which would allow for easy discoverability.

How

cc @Baxxster

As far as I know (once #1 and #2 are resolved) the book will be hosted at https://openra.github.io/book.

How this should be done technically I do not know 😢but I'd love to learn if someone is in a teaching me!

Why

The gitbook CLI and self-hosted option is deprecated in favor of Gitbook's (paid) hosted solution.

Pros

mdbook...

• unlike gitbook, does not target revenue so will remain open and free

• provides native binaries (via github releases) so we can drop the dependency on the nodejs runtime

• has 4 built-in themes

Cons

• as far as I can tell, mdbook does not have a plugin system like gitbook, but this will probably not be an issue for us
  • mdbook does have a similar system

Since OpenRA/OpenRA#14859, ^ are limited to be used for templates and can only be used for entries to be inherited from while not being actors themselves.

The format standard for this book should be in an in-tree document.

These bullet points are some of the rules I have generally tried to follow so far and believe we should follow going forward. There are undoubtedly more that I can not think of right now.

• generally 80 columns per line max, with some exceptions:

  • if a single char of punctuation goes over 80 that's fine
  • avoid orphans if at all possible
  • ...

• links should go at the bottom of the document (see the current README.md as an example)

OpenRA/OpenRA#15852 is not mentioned anywhere in the current docs. Imho we should include it in this new iteration of the docs.

https://github.com/peaceiris/actions-mdbook

Related Tickets

#1 - Publish book to GitHub Pages via Travis CI

Description / How

Create a Personal Access Token for the orabot GitHub account with the public_repo scope.

Then follow these instructions to add it to the OpenRA/book repo settings on https://travis-ci.org.

Why

This is required by the deploy step of Travis CI to create / push to the specified branch (gh-pages in our case).

Who

@pchote, because they have access to the orabot GitHub account and the OpenRA account on https://travis-ci.org

One such tool is oraide.

pchote has already enabled this repo in the openra account on https://travis-ci.org, now we just need a .travis.yml file that will actually build and publish the book.

https://creativecommons.org/licenses/by/4.0/

I believe maps can not contribute, for example, palettes. . Maps can contribute palettes!

Per @penev92 on Discord only tiles and factions can not be contributed by maps.

https://discordapp.com/channels/153649279762694144/160191522053160960/620736487176273930

Documentation for the release tab appears to still traits reflecting Release 20200503 and hasn't been updated for Release 20210321.

https://forum.openra.net/viewtopic.php?p=310747#p310747