Minetest: Consolidate API documentation

[tacotexmex]

Issue type

• Documentation issue

Summary

lua_api.txt is quite messy. Wiki is constantly out of date. (Show of hands all who still _love_ working with MediaWiki 😉 )

What about a consolidation of the API documentation to a single source of truth, served as a automatically generated rich static web page that's actually legible?

There are many generators, Slate is one of them.

Pros

• Legible design
• Everything on a single page (avid Ctrl+F:ing lua_api.txt users would still feel at home)
• Slate is just Markdown (lua_api.txt is Markdown too, at least to a large degree)
• Out-of-the-box syntax highlighting
• Still hosted on Github (workflow won't have to change much)

Cons

• Some reorganizing of lua_api.txt probably needed
• If hosted in a separate repo, separate PR needed (so let's not)
• Arbitrary argument about the modern web, specific style or overhead

Quick FAQ

• Slate is ugly/wrong language/wrong license
  
  
  
  • Let's be clear that Slate is _only one example_ out of many.
  
  
• Why don't you just do it yourself?
  
  
  
  • I could, but if people pushed updates to lua_api.txt the old way it'd get outdated before I could say mese. (the wiki problem)
  
  
• I like it the way it is, real developers should read text files anyway
  
  
  
  • Good for you, but what about aspiring ones? Let's lower the bar, because everybody likes legible documentation.
  
  

[HybridDog]

If you use the md extension, github displays lua_api like that: https://github.com/HybridDog/md_test/blob/master/lua_api.md

[rubenwardy]

I'd like to see this done, and see this done well. As well as not being particularly great as plain text, the reference is currently a massive pain to search through and find anything.

If you use the md extension, github displays lua_api like that: https://github.com/HybridDog/md_test/blob/master/lua_api.md

There's also this: https://rubenwardy.com/minetest_modding_book/lua_api.html

[4w-zz]

lua_api.txt is quite messy.

Related: #6850

[paramat]

As long as lua_api remains in the minetest repo as a .txt file this is fine by me (it has to be .txt for reasons explained elsewhere). Automatically fetching it and displaying in MD format somewhere else is a good idea, it pleases both those who want to look at lua_api in MD format and devs who need it to be .txt to be able to work with it in Github.

There are other documents that could be included in this too, like client_lua_api.

[rndevuk]

@paramat could you explain what these reasons are or point me in the direction of where to locate the reasons. thanks

[paramat]

See #6707 and the discussion in IRC http://irc.minetest.net/minetest-hub/2017-11-28#i_5150747
Being a .md file makes a file impossible to work with in Github, i use search several times daily to go to lines in lua_api.txt, and to help people i need to be able to give someone a link to line in the file.

[rndevuk]

OK i have nothing against the text file being in there... but if your reason is so that you can refer people to a specific line... then any good document software would have anchor points and search facilities available to it.
Meaning if it is done properly you should be able to still link to lines and do searches.

I think the lua_api.txt is making people lazy, that information should be in the wiki.
If I'm not mistaken there is an unspoken rule that pull requests must have a relevant entry in the api.txt but realistically the rule should be forcing people to keep the wiki updated with there own changes.

also making it possible for people to log into the wiki with there github accounts might make people more inclined to keep it updated too

just my 2 cents.

[tacotexmex]

any good document software would have anchor points and search facilities available to it

This. 👍

making it possible for people to log into the wiki with there github accounts might make people more inclined

More inclined is not enough I believe. Let's automate the crap out of it first, then we can see where enrichment of docs is needed the most.

[4w-zz]

Linking to lines is just a convenience function. Linking headings in Markdown files on Github works very well.

Example: https://github.com/minetest/minetest/tree/e7f16119913f7b2c98059398085d410684c9d8c0#command-line-options

This is less exact than making a specific line (don't forget to press Y afterwards to get a permanent link to the commit state you maked the line in!) but not being able to link to a specific line should not be the only reason not to properly use Markdown parsing.

[paramat]

then any good document software would have anchor points and search facilities available to it.
Meaning if it is done properly you should be able to still link to lines and do searches.

But this doesn't happen in Github. When developing, searches need to be done in Github that return results from code and lua_api.txt, to get all the relevant information. These sort of searches are essential for developers and we do this several times a day.
I can't really express how important this is for developers.

Referring people to lines in lua_api is the less important point, that can indeed be done if it is hosted elsewhere, however, it would be irritating to do so elsewhere instead of in Github where a developer is already signed in. The difference is i would not be bothered to quickly link someone to something if i had to go outside Github to do it. I link people to stuff because it can be done quickly and easily inside Github.

I think the lua_api.txt is making people lazy, that information should be in the wiki.

No we're not lazy. The wiki is an alternative source of information, but the official and up to date documentation is the lua_api in the repo. We direct people to the repo version and keep it instantly up to date in commits. Updating the wiki also is time consuming and irritating duplicate work, devs have a severe lack of time for MT so keeping the wiki updated is something left to non-devs. We would never force devs to update the wiki, i would refuse to do that and most devs would, for good reason.

More inclined is not enough I believe

Correct.

not being able to link to a specific line should not be the only reason not to properly use Markdown parsing.

It isn't, but it is a factor.
The ability to link to a header is irrelevant in this discussion.

Documents being .txt has been celeron55's policy throughout MT history, and is for many other reasons than the one's i describe. The suggestion of this issue is a good way to keep everyone happy.

[4w-zz]

The wiki is an alternative source of information, but the official and up to date documentation is the lua_api in the repo.

This should be mentioned clearly and on any page in the wiki. Ideally via header on all pages implemented via wiki template for pages.

The ability to link to a header is irrelevant ~in this discussion~ for me.

FTFY

[paramat]

Linking headings in Markdown files on Github works very well.

Well yes it is irrelevant when discussing the ability to link people to certain lines, each section is long and we can't have a header on every line.

[4w-zz]

So, no matter what (Markdown or text, both work as needed) ... but redundant documentation is useless. So it either should be automated to create properly readable (parsed) documentation from Markdown or lua_api.txt (and the other documentation) should be used exclusively, deleting the outdated other documentation elsewhere.

Right now the dev wiki adds no value at all. It only causes confusion because of being outdated in a lot of places.

[tacotexmex]

I think the wiki still provides a lot of value but the coverage is patchy. That _may_ be mitigated here but let’s see what the page generator can do first.

[tacotexmex]

Any ideas on how to start processing lua_api.txt? If I fork it, my version will become outdated after next upstream commit. Keep a close sync with upstream, daily PRs? Temporary freeze for lua_api.txt commits? I want to get started but I don't want to throw work away.

[paramat]

First there needs to be agreement on what happens to lua_api.

What about a consolidation of the API documentation to a single source of truth

An issue with this is that the wiki tends to have longer and clearer explanations, while lua_api needs to be fairly concise. Replacing both with one document that is inbetween then compromises both clarity and conciseness. When a PR is made that alters lua_api, contributors don't have time to be overly explanatory or compose a webpage type format (although i agree with making lua_api a little more clear and descriptive, and it is becoming longer and clearer).

So lua_api needs to stay as fairly simple plain text, but could be a little more descriptive.
I think it would be too much work, and unsuitable, for one person (such as yourself) to go through lua_api and rewrite everything to be clearer. Each section needs to be edited by a person who is an expert of that section. This will take a long time and many different people, and likely will only happen as we update it.

How about:

• We keep the wiki, because although much is out of date there is still a lot of useful stuff there and lots of work has gone into it.
• A new place to view lua_api in MD display is created, that automatically updates from the lua_api.txt in the repo (what this issue is about).
• We decide from now on to make lua_api a little clearer, better organised and a little more explanatory as we update it (to an extent this is already happening).

[4w-zz]

We keep the wiki, because although much is out of date there is still a lot of useful stuff there and lots of work has gone into it.

As said earlier: The best would be having a clearly visible note on all pages that the information may be outdated and that in case of differences the lua_api.txt (or .md, or folder, or whatever it will be) is the correct documentation.

Or create a wiki template like ´{{outdated}}´ authors/users can set who noticed that the page is outdated but ton't have time/knowledge to fix it so others will be warned.

A new place to view lua_api in MD display is created, that automatically updates from the lua_api.txt in the repo (what this issue is about).

Maybe first transfer everything as a whole to the new place and over time slowly phase out lua_api.txt by transferring sections to the new system on updates. A searchable page where it is possible to reference specific lines that uses whatever file/files as source is absolutely possible and pretty easy to code.

This would allow having the documentation in maintainable smaller pieces that can be extended without bloating the file too much (because they're all individual files) and having a line-referenceable "front-end" where all the individual files are combined.

[rndevuk]

i genuinely believe that the best way forward would be to find a doxygen solution that automatically creates documentation for all of the classes/objects and variables within minetest source.

doing that would actually probably eliminate the need for any of the above mentions ideas. http://www.stack.nl/~dimitri/doxygen/index.html

once a relevent software is found to do the job. travis could be setup to create it i think....(don't quote me on that last bit though)

[4w-zz]

i genuinely believe that the best way forward would be to find a doxygen solution that automatically creates documentation for all of the classes/objects and variables within minetest source.

Having documentation in the code and use any system to create the documentation page/file from that in-code documentation would be the absolute 100% top plus version of a solution.

But I doubt that this will ever happen here 😞

[rubenwardy]

I suggest exploring the use of luadoc. You could make a file called documentation.lua which has all the signatures of functions and comments about them. I'm not sure how good it is at other things though

[pilino1234]

i genuinely believe that the best way forward would be to find a doxygen solution that automatically creates documentation for all of the classes/objects and variables within minetest source.

http://doxy.minetest.net/ exists for the engine, something similar for the lua API would be great

[rndevuk]

http://doxy.minetest.net/ exists for the engine, something similar for the lua API would be great

never knew that existed, and yeah i agree, same thing needs to happen for the lua api.

https://github.com/alecchen/doxygen-lua

doxygen can be used with lua too...

[4w-zz]

http://doxy.minetest.net/ exists for the engine, something similar for the lua API would be great

Woah! 👍 Should totally be done for the Lua API, too!

[rubenwardy]

Doxygen sucks for Lua, I've tried doing it before. LuaDoc or LDoc are better choices

[rndevuk]

Doxygen sucks for Lua, I've tried doing it before. LuaDoc or LDoc are better choices

Il have to take your word for it I've never dealt with documenting Lua before :D

[tacotexmex]

LuaDoc is obsolete, use LDoc instead → https://github.com/stevedonovan/LDoc

[rubenwardy]

Ah, I never remember which one is which

[tacotexmex]

☝️ is the instant result of dropping the current lua_api.txt into Slate. (Also check default example)

I still believe Slate could be a good candidate as it inherits most qualities of the current lua_api workflow, is still single file, grants instant legibility, has search (although not seen in the screenshot)

[rubenwardy]

How searchable is it?

[tacotexmex]

You may try search in the default example Slate. It's fast!

As seen from the screenshot it's clear that lua_api would need adjustments in any case. It's not quite Markdown validated to say the least, just check the bottom of the screenshot. So Markdown fixes and some restructuring (more heading levels giving better Slate sectioning) is what is needed for the above. When it can truly shine is if/when we break out code examples into the third column. 😋

[rndevuk]

I do like slate :D from what ive seen anyway :D

[paramat]

We can't phase out lua_api.txt, it's essential to have it in the repo to be updated by commits, but lua_api.txt could certainly be spilt into smaller parts.

find a doxygen solution that automatically creates documentation for all of the classes/objects and variables within minetest source.

Having documentation in the code and use any system to create the documentation page/file from that in-code documentation would be the absolute 100% top plus version of a solution.

Seems a bad idea with obvious and serious issues:

There is a lot in lua_api that is not suitable for moving into code.
What a doxygen type program produces from the source code will not be consisely formatted for readability and clarity, the program is now dictating how the information is presented, instead of our own editing. The result will be less clear.
Documentation obviously has to be accessible as plain text without the need for extra software to view it. If you don't have that software (you can't assume everyone always has access to the viewing software) then someone has to search around in code not knowing where to look for the information, which makes the documentation useless.

Requiring extra software to view something as simple as documentation is ridiculous and unacceptable. It has always been intended in MT that documentation is viewable in simple plain text form, because that form is so universal and so easily accessible.

[4w-zz]

the program is now dictating how the information is presented

You can say it like that ... oooor, you could say: "It processes the data to be presented in a standardized form being easily viewable by everyone without having to adapt to yet another 'best form' of representation".

Requiring extra software to view something as simple as documentation is ridiculous and unacceptable.

Agreed. It has to be available offline and it has to be accessible without additional software. This does not mean it has to be plain text and it does not mean that it can't be processed from a source.

[tacotexmex]

Agree with most mentioned since my last post.

We can't phase out lua_api.txt, it's essential to have it in the repo to be updated by commits, but lua_api.txt could certainly be spilt into smaller parts.

What would those smaller parts be? I'm thinking a split may not be necessary given how, if provided a sane document hierarchy, Slate can deal with large amounts of sections.

[4w-zz]

What would those smaller parts be?

Thematically grouped sections of the current documentation file.

[tacotexmex]

Thematically grouped sections of the current documentation file.

Right. Regardless of if splitting the file or not, we need a clearer structure for its content. So I'm looking for software that can analyze markdown hierarchy. Any ideas?

[4w-zz]

Any ideas?

Maybe render to HTML and use W3C validator. Iirc it provides the outline based on headings.

[tacotexmex]

Maybe render to HTML and use W3C validator. Iirc it provides the outline based on headings.

~How does that improve the hierarchy of the Markdown though?~

I see what you mean and it works, but I need to be able to move around the hierarchy in the Markdown.

[4w-zz]

You need to manually move the text and/or change the Markdown to alter the depth.

Maybe there are WYSIWYG editors for markdown rendering the text and allow moving it around without manual editing of the underlying Markdown source. But I don't know any.

[apachano]

Well I want to help go through and better document the API so I might as well join the conversation. I feel like pulling the comments from the code itself in a similar form to doxygen would be best, from there automation tools (existing tools or tools to be made) can move the documentation to various different areas such as the lua_api.txt, a website, and potentially making the information available to the custom IDE plugins that have been in development.

Essentially the information would be pulled from comments next to the actual functions being called and everything else would be auto generated from there. The lua_api.txt would exist for those who like to use it and other formats would also exist per user preference getting all of the information from a single location. All of the information would then be synced and outdated information would not be an issue.

The problems
1) How much information is appropriate to put next to function prototypes, the wiki has examples and other things that wouldn't be.
2) What tools are appropriate to do this and how much work has to be done/ who is willing to help.

Paramat, as far as things that are not suitable to go into code (I assume introduction, startup, paths, other non function related things) There could be other files to pull the information from. a system with standards compatible with automation would just have to be set in place.

Edit: This could be expanded into support for mods as well. It would be more complicated but worth it in my opinion.

[rndevuk]

i think @apachano has the right idea...

[tacotexmex]

I think the next step is to set up some type of demo of the above mentioned systems so that we may estimate their capabilities.

[apachano]

Well you suggested slate can you put a demo together for that? My suggestion would involve development work and a lot of discussion to put it together.

[4w-zz]

How much information is appropriate to put next to function prototypes, the wiki has examples and other things that wouldn't be.

Why? If comments are used for documentation it is absolutely fine to provide examples. Since most of the stuff is taken automatically from the function/etc. this information can be omitted. Just focus on function documentation and examples in the comments and let the system do the rest.

[tacotexmex]

Well you suggested slate can you put a demo together for that?

I did, here. I managed to get automatic builds via Travis CI. Now I only need to figure out how to watch lua_api.txt and automatically pull changes for new builds.

It is what it is (not pretty) but it's up at least. I didn't change anything other than copy-pasting lua_api.txt into the markdown file and made a lua-tab for future code examples. Catastrophies such as these are entirely due to bad Markdown syntax.

[apachano]

What is up with the weird right side? Regardless it would work well enough. Does slate only take in .md and output html? Can it be made to output a pdf? Can it be set to pull a source then output a .md? Can we take the output and use it for custom features (IDE Integration)?

[pauloue]

@tacotexmex The catastrophes where actually caused by a pesky line in config.rb that disabled all indented code blocks. See my slate for the fixed version. I also disabled the examples column so that everything isn't crowded with a browser/editor split screen.

I also made an update script. I don't know how I could do it automatically though.

[tacotexmex]

@apachano The right side is as stated and shown before, the place for code examples and the like. Again, see the default example.

Yes Slate converts Markdown to HTML. (Not PDF, why on earth would we want that?)

I don’t know what ”custom features” you need for your project, but lua_api.txt is already Markdown.

@pauloue That’s good! But the code examples panel is a good thing and by botching it you also disable the mobile viewport and made the lines too long to be legible). For automatic deployment, use Travis.

In general the idea is to make lua_api.txt look good in Slate, not make Slate look good with lua_api.txt.

[pauloue]

I meant automatically deploying whenever lua_api.txt is committed to, but I'm guessing that's not possible. My update script is for updating the lua api, not deployment.

I guess the examples column could be nice if lua_api.txt is changed to work with this format.

[tacotexmex]

I meant automatically deploying whenever lua_api.txt is committed to, but I'm guessing that's not possible.

Did you even read my posts? 👇

Now I only need to figure out how to watch lua_api.txt and automatically pull changes for new builds.

I guess the examples column could be nice if lua_api.txt is changed to work with this format.

That's the whole point of my issue, 1st post:

Some reorganizing of lua_api.txt probably needed

[apachano]

PDF because everyone is different, idk who but other documentation programs tend to have a large range of outputs. We also can't focus on just making the html page look nice, some developers are going to still want a text file (well formatted as well) to look through. The big thing is finding a solution that can work for anyone.

As far as custom features I mentioned use integration, Idk much about lua environments but with javadoc your ide will pull information automatically from the documentation for help in the ide, plugins should be able to be made to do similar with lua.

Edit: pdf format if you want a printed guide sitting next to you while you work, I have met developers who like hard copies to flip through.

[rubenwardy]

I tried searching for "ObjectRef" but the search tool wasn't able to find it, despite it being the exact wording of a title

[4w-zz]

I tried searching for "ObjectRef" but the search tool wasn't able to find it

Well ...

... and ...

[rubenwardy]

It should find this: https://github.com/minetest/minetest/blob/master/doc/lua_api.txt#L3917

### `ObjectRef`
Moving things in the game are generally these.

This is basically a reference to a C++ `ServerActiveObject`

[tacotexmex]

That's not good. We can always turn search off and refer to Ctrl-F but that'd be sad.

[tacotexmex]

That's not good. We can always turn search off and refer to Ctrl-F but that'd be sad.

Other than Slate there's also Read the Docs which seems really capable than Slate but isn't static, serves some ads and someone called @MikeHolder currently holds the minetest account.

[tacotexmex]

Looking into how to Trigger a Travis CI build from another project’s build. Anyone got experience with this?

[pauloue]

With Travis you can enable a cron job with daily builds. If the build script pulls the latest version of lua_api.txt first, you can have automatic daily updates. The most recent commit to my gh-pages branch was done this way.

[tacotexmex]

Good work @pauloue. Now that we know that we can have completely automatic builds of lua_api.txt, we need to decide if Slate is viable. @rubenwardy had issues with search for example.

Speaking of Read the Docs I saw that it supports versioning, internationalization and multiple export formats (including PDFs).

[Ezhh]

... serves some ads ...

I'd really prefer we don't use things that come with ads.

[apachano]

I've already started trying to set up read the docs (minetest-sonos on there), some work has to be done to our documentation to make it compatible but I have used sphinx in the past and I like it.

Sphinx can also be built locally into any of the supported outputs. If you don't like advertizements build it on your own system. We can also automate it and host it on our website or at github pages.

[pauloue]

I suggest we start working on this to further evaluate slate:

Some reorganizing of lua_api.txt probably needed

I re-enabled the examples column on my slate and switched it to fetch the lua api from the lua-api-slate branch of my minetest fork and began working on some of the issues. I'll keep it up to date by merging upstream changes.

[pauloue]

I got another HTML version up at pauloue.gitlab.io/minetest-api/mods/. It gets automatically regenerated daily and includes a LaTeX PDF version. It has a table of contents and lots of anchor links.

[paramat]

That's really nice, thanks for that. It's a little more readable than rubenwardy's.

My opinion on this issue is still as in https://github.com/minetest/minetest/issues/7084#issuecomment-370899739
We can't combine the wiki and lua_api.txt as the official source (lua_api.txt) has to remain concise and text-based to be manageable when making a PR.

[rubenwardy]

It has a table of contents and lots of anchor links.

My version has an anchor link per code snippet in a bullet point too, which is useful for this:

https://rubenwardy.com/minetest_modding_book/lua_api.html#minetestwrite_jsondatastyled

I do need to work on the loading speed however, as it lags a bit for me

little more readable than rubenwardy's.

The line spacing is better when there's inline code. I need to fix this in my version (and the rest of the book)

---

:+1: to reorganising lua_api.txt in a way that makes it a lot easier to search and make a HTML version. Slate could be good for this if its search function can be utilised

[ClobberXD]

@paramat: Here's an advantage of using anchors - sections in lua_api.txt could have permalinks to relevant documentation in another part of the file, without the problem of the links pointing to the wrong place (which is the case when permalinking to line numbers) after a couple of commits.

e.g. The section on Nodes could also have a perma-link to the Node Definition (at the bottom of the file) used during registration.

[paramat]

I probably won't mind what happens as long as lua_api.txt stays as .txt and remains readable and usable in .txt form. What concerns me is what might be done to it for the sake of display in another form. MD symbols are not too bad but has made it a little messy in .txt form.

Remember that it is used by core devs in .txt form on GitHub because any other form makes it impossible to work with.

[rubenwardy]

This needs to change despite your feelings about it, paramat. Users find it hard to use the document which is why a lot of users try to solely use the wiki. It's possible to have both a version controllable text document and a searchable output document

[paramat]

I'm not opposing a change, as is clear from my previous comment, my opinion will depend on what is proposed. I think you misunderstand.
I've done a lot of work to improve the document, probably more work than anyone. See the history of commits. The order and clarity is now much improved. Some others have made more complex plans but then not done anything ;)

It's possible to have both a version controllable text document and a searchable output document

I know, i'm just being careful about the readability of the .txt. version being seen as lower priority, as i know from issue discussions some see it that way. It is equal priority to any other version.

My only disapproval is this (stated twice above):

We can't combine the wiki and lua_api.txt as the official source (lua_api.txt) has to remain concise and text-based to be manageable when making a PR.

Which is part of the original issue request.

[paramat]

I agree we need a way to present the document that has a table of contents linking to sections, is searchable, and anchor links will be useful too. It needs to be auto-updated daily from the repo lua_api.txt. So essentially like rubenwardy's or pauloue's presentation but with improvements.

I feel that rubenwardy's site is not the right place for the official presentation location of the document, instead i suggest it is on the Minetest website.

I tried searching for "ObjectRef" but the search tool wasn't able to find it, despite it being the exact wording of a title

Possibly fixable by removing the `` from class section titles, they're unnecessary and inconsistent anyway. So Slate may be fine.

Something that will accept the MD formatting so that we don't have to completely redo that. It's useful for the document to be viewable in MD display.
Also, something that doesn't make much mess in the .txt. version or when opened in MD display.

[pauloue]

I didn't have an issue finding the ObjectRef section title in slate, but I don't see why people would use the slate search instead of the naive browser search which is faster, lets you jump between each result, and has useful options.

In any case, I don't think slate is a good option since it would require significant changes to lua_api.txt, some of which wouldn't make much sense outside of slate. These include using blockquotes for code annotations, putting the examples before the explanations, and removing non-example code blocks.

For my HTML version I moved the table of contents to a fixed side position like slate to avoid having to scroll up.

[rubenwardy]

i don't see why people would use the slate search instead of the naive browser search which is faster, lets you jump between each result, and has useful options.

Because I want to see the reference for something, not every flipping time it's mentioned

[pauloue]

Another one, Read the Docs-style: https://pauloue.github.io/lua_api/

[tacotexmex]

pauloue's RtD version is excellent, can this be officially adopted? Perhaps at lua_api.minetest.net or maybe at docs.minetest.net/api/lua?

[paramat]

^ Yes i agree, what pauloue has done is exactly what i prefer and i would like to see this approach official (as far as i know it's even better than rubenwardy's). The text document is maintained as before (as is necessary) but a friendly presentation is derived from it.

[paramat]

Done in #8133
Link http://minetest.gitlab.io/minetest/

[tacotexmex]

Good job everyone! What does it takes to serve it at minetest.net?

[paramat]

Yes we need to add a link from the site.

[tacotexmex]

No, why should it be hosted on the Gitlab domain at all? Why not minetest.net?

[paramat]

I think there's a good reason, maybe because it needs to be regularly updated from MT code.
@pauloue
Also, nerzhul wrote: "We can bind a minetest.net domain on it if needed."

[pauloue]

It's hosted on GitLab pages for automatic updates, but a minetest.net subdomain can be setup for it, as nerzhul says. GitLab docs: https://docs.gitlab.com/ce/user/project/pages/getting_started_part_three.html.

[appgurueu]

Please reopen this. The current state of the documentation still can be improved.

[paramat]

The requests in the first post have been implemented.
The issue author tacotexmex commented after the close with:

Good job everyone!

And did not complain about the issue being closed.

So, if you have further requests for improving documentation (i do not deny it could be further improved) please open a new issue. This one is old, long and full of discussion that is now irrelevant or out of date due to the hosted API documentation.