Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Move nml docs to be in repo, build with jekyll/sphinx/readthedocs etc #44

Closed
andythenorth opened this issue Oct 13, 2019 · 5 comments
Closed

Move nml docs to be in repo, build with jekyll/sphinx/readthedocs etc #44

andythenorth opened this issue Oct 13, 2019 · 5 comments

Comments

@andythenorth
Copy link
Contributor

andythenorth commented Oct 13, 2019 •
edited

Current

nml docs are in the newgrf wiki

Upsides of the wiki:

  • docs can be fixed independent of nml releases
  • anyone can contribute
  • in same place as nfo docs and general newgrf information
  • searchable

Downsides of the wiki:

  • documentation is divorced from PRs that add features to nml
    • docs often define what the spec is
    • absence of docs makes reviewing harder
  • wiki cannot provide docs for unreleased features
    • makes it hard to get feedback / pre-release testing from newgrf authors

Contentious bits:

  • I don't like wiki markup
  • .md and friends have won for documenting code and libraries, wikis are just not as good for this use case

Desired

  • replace wiki for nml with docs in the repo

  • use .md or .rst whichever is considered to be winning

  • leave the wiki in place for nfo and general newgrf info

  • build and hosting options:

    • jekyll (native github) and use github pages (faff when I tried - requires weird set up)
    • sphinx and hosted https://readthedocs.org/
    • our own parser and push to S3 bucket or or coop bundles or digital ocean or something
@andythenorth
Copy link
Contributor Author

There might be automated wiki scrapers to do this, or maybe it can just all be rebuilt by copy-paste. Job for long winter evenings 👍

@MinchinWeb
Copy link

Since the rest of the code is in Python, Sphinx might be a good option. (Sphinx is also written in Python, Jekyll is in Rub.) It should be possible through GitHub actions to build the documentation, and then push it to GitHub pages (effectively the "gh-pages" branch of this repo) and host it from there. I've done this with previous project via Travis-CI, but haven't tried yet with GitHub Actions.

@nielsmh
Copy link
Contributor

nielsmh commented May 3, 2020

I'd be in favour of not using an automated tool to convert the docs, but do it manually. I don't particularly like the structure on the wiki and many sections (especially regarding basic syntax) seem unclear or even incomplete to me.

Also, while Markdown is popular, I think we should consider just writing things directly as HTML. Publishing will be a simple file copy (or upload). It will be readable, with formatting, unmodified on any user's computer. The documentation does use lots of tables which are IMHO annoying to work with in MD.

@Alberth289346
Copy link
Contributor

asciidoc is nice, it is Eclipse documentation standard, comes close to expressiveness of Sphinx with simpler syntax.

asciidoctor is a popular implementation, manual at https://asciidoctor.org/docs/user-manual/

@andythenorth
Copy link
Contributor Author

TMWFTLB

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@nielsmh @MinchinWeb @andythenorth @Alberth289346