2024-03-19 09:41 CET

View Issue Details Jump to Notes ]
IDProjectCategoryView StatusLast Update
0005753Spring engine[All Projects] Generalpublic2017-09-10 14:08
ReporterAF 
Assigned To 
PrioritynormalSeverityminorReproducibilityN/A
StatusnewResolutionopen 
Product Version 
Target VersionFixed in Version 
Summary0005753: Move Engine documentation
DescriptionI offered on GitHub to move the engine documentation to markdown in git for evaluation if seriously considered. If accepted then I would move the docs out of the wiki so there was no duplication, and ensure the wiki redirected or linked to the relevant places

This would mean:

 - every copy of the source code would contain build instructions and docs
 - docs are fully version controlled
 - Jekyll can be used to build the docs into a site with full client side search
 - Theming the docs would be significantly easier to do, and to maintain
 - A big boost to readability and UX
 - Syntax highlighting
 - Users can edit via GitHubs web interface without needing to know git, improving security, 2FA anybody?
 - The end output is static HTML files, no database to maintain, can remain 100% versioned and super fast to load
 - Docs can be automatically tested and built via Travis and GitHub
 - GitHub pages can provide free hosting or as a backup should springrts.com go down
 - Markdown is easier to read raw than wikimarkup
 - Developers normally don't expect to have to go to a different site to view build instructions, this corrects that issue

Before I continue though, I'd like to ascertain that there is interest in this and that it'll be fairly evaluated. I don't want to put the work in if the decision has already been made
Additional InformationI've been working with the tech to do this for a while, with multiple projects, I'd likely start with this particular Jekyll theme as it makes for a good handbook/reference with some small modifications:

https://long-pig.cloudvent.net/

TagsNo tags attached.
Checked infolog.txt for Errors
Attached Files

-Relationships
+Relationships

-Notes

~0018354

abma (administrator)

"to move the engine documentation to markdown in git"

can you be more specific? what is the "engine documentation"?

i.e. there
- is doxygen comments in the source code
- are wiki pages wrt engine development
- are wiki pages wrt lua api
- ...

having everything in the source code of spring would mean that there would be a lot commits which changes docs: it would be difficult to filter doc and code changes.

how do you want to do it? add markdown files to the git repo in folder docs/?

as i understand you want it to add to the source code: on very commit CI is used: i.e. the engine is recompiled, thats not very useful when only documentation is changed.

~0018360

AF (reporter)

Everything in the Wiki under Engine and Native Development:

Engine and Native Development
Engine Development Starting point for engine development.
Compiling Engine How to build the Spring engine from source.
Lobby Development (Clients and Servers) Information regarding contributing to the source code of the different lobby clients and servers available for Spring.
AI Development Lots of information about developing Skirmish, and Unit AIs for Spring.

Doxygen is automated documentation, I wouldn't move that all for the same reason it isn't inside mediawiki

> having everything in the source code of spring would mean that there would be a lot commits which changes docs: it would be difficult to filter doc and code changes.

Other projects solve this by using either a gh-pages branch or dedicated docs branch, or they use a separate repo for documentation. I'm not a huge fan of having a tonne of jekyll templates in a subfolder of the engine code. Having said that I would expect documentation changes to go through a Pull request process so that they can be reviewed and checked.

> are wiki pages wrt lua api

I don't think Media wiki is the the best representation, nor does the organisation really help much, but I wouldn't include this in the first batch. If after the engine native stuff is checked out and it's all good I'd be interested in automating Lua API doc generation, or at the very least, something that will bootstrap docs so people can then add to it, but that's something I'd prefer not to think about too much right now, there are a lot of options to explore.

As an aside, there's a mediawiki plugin that lets you embed files from GitHub, so redirections or manual synchronising to prevent duplication would be unnecessary.

~0018363

abma (administrator)

moved to "engine" as this affects basicly everything (wiki, engine, build infra, ...)

~0018367

AF (reporter)

On a related note, I've a similar project where I'm taking an existing markdown site built with Jekyll and porting it over to use a modified edition theme running on GitHub pages here:

https://tomjn.github.io/varyingvagrantvagrants.org/

search: https://tomjn.github.io/varyingvagrantvagrants.org/search/?q=utilities

I'm currently working on applying some rebranding stuff with a new logo, and need to implement the blog posts/news page, which I estimate is 20 min of work. Those docs used to be in the main repo under a docs folder, but we had to cherry pick commits into master to deploy updates, so it was moved into a dedicated repo on a continuous deployment process

--------

Going forward for Spring, I would expect we would name the Jekyll built site the engine handbook, and that given the nice sidebar nav we could make some pretty easy wins improving things just by ordering the pages correctly and breaking long articles into subpages

When I'm back from Canada I can do the following:

 - setup a mediawiki instance with the embed plugin and a copy of the latest available spring wiki data
 - Setup GH Pages and a repo with the engine section of the wiki in markdown
 - test embedding those pages in mediawiki
+Notes

-Issue History
Date Modified Username Field Change
2017-09-07 15:07 AF New Issue
2017-09-07 19:01 abma Status new => feedback
2017-09-07 19:01 abma Note Added: 0018354
2017-09-08 22:21 AF Note Added: 0018360
2017-09-08 22:21 AF Status feedback => new
2017-09-09 19:48 abma Project Site => Spring engine
2017-09-09 19:48 abma Category wiki => General
2017-09-09 19:50 abma Note Added: 0018363
2017-09-10 14:08 AF Note Added: 0018367
+Issue History