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

Refactor markdown files #14287

Open
wants to merge 78 commits into
base: master
Choose a base branch
from
Open

Refactor markdown files #14287

wants to merge 78 commits into from

Conversation

Bituvo
Copy link
Contributor

@Bituvo Bituvo commented Jan 20, 2024

Ready for review

This is a better version of #13503, but without so much noise. Only markdown files (and worlds_here.txt) were changed.

This PR adds these things to the documentation:

  • Modern primary and secondary headings
  • Capitalized headers
  • Slightly less whitespace before primary headers (three lines)
  • Github flavored warnings and information boxes
  • Lua code blocks where appropriate
  • Tables where appropriate
  • Inline code blocks where appropriate
  • Removal of extra whitespace in tables ({ min=3, max=5 } -> {min=3, max=5})
  • Typo fixes (especially id instead of ID)
  • Removed table of contents from /README.md as Github has a builtin one
  • And more

To do (preferably in a different PR, just putting it out there):

  • Use a consistent maximum line width (maybe increasing with each level of bullet points)
  • Scour for typos and other mistakes
  • Redo protocol.txt

Some people still use the plaintext version of the Lua API, so I tried to maintain readability while still simplifying things.

@Bituvo Bituvo changed the title Doc refactor 2 Documentation Refactoring Jan 20, 2024
@Bituvo Bituvo changed the title Documentation Refactoring Refactor markdown files Jan 20, 2024
@appgurueu
Copy link
Contributor

appgurueu commented Jan 20, 2024

First, an observation: This PR does not require a core dev to review it. I suggest the @minetest/docs team (or anyone trustworthy, really) be allowed to review this (and have their approval count).

Github flavored warnings and information boxes

I recently (regrettably) pushed such a change; I'll have to fix it (or you could fix it here too, if you want). This seems to not render correctly on https://api.minetest.net. I think we want to stick to plain Markdown, for now.

@Zughy Zughy added the Action / change needed Code still needs changes (PR) / more information requested (Issues) label Jan 22, 2024
@Bituvo
Copy link
Contributor Author

Bituvo commented Jan 23, 2024

Github flavored warnings and information boxes

I recently (regrettably) pushed such a change; I'll have to fix it (or you could fix it here too, if you want). This seems to not render correctly on https://api.minetest.net. I think we want to stick to plain Markdown, for now.

That website uses MkDocs, which supports extensions. There are already a few extensions enabled here and after some searching I found https://pypi.org/project/markdown-gfm-admonition/, which enables Github admonition boxes. I personally haven't tried testing this extension (I am too busy), but it looks promising, to whoever may be able to try.

@Bituvo
Copy link
Contributor Author

Bituvo commented Jan 24, 2024

@Zughy Whose opinion should I get on this?

@Zughy Zughy removed the Action / change needed Code still needs changes (PR) / more information requested (Issues) label Jan 24, 2024
@Zughy
Copy link
Member

Zughy commented Jan 24, 2024

It was about the GH info boxes but I guess it's been solved

@Bituvo
Copy link
Contributor Author

Bituvo commented Apr 21, 2024

@sfan5 Thank you so much for digging through this pull. I would never have the time or energy to do it myself, so help is always appreciated. I hope you agree with my changes.

@sfan5
Copy link
Member

sfan5 commented Apr 27, 2024

Should be fine, can you merge/rebase the last tiny change?

doc/lua_api.md Outdated Show resolved Hide resolved
doc/lua_api.md Outdated Show resolved Hide resolved
doc/lua_api.md Outdated Show resolved Hide resolved
doc/lua_api.md Outdated Show resolved Hide resolved
@Bituvo
Copy link
Contributor Author

Bituvo commented Apr 27, 2024

Merge conflicts have been resolved.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

7 participants