Documentation

[badcel]

As we settle more and more on specific decisions how to progress, there is some need to document this project for our self and potential users.

From my point of view there are 3 kinds of documentation needed:

• API documentation: Which APIs are available?
• Developer documentation: How does everything work?
• User documentation: How to use the libraries?

We have several possibilities on how / where to document and should find a solution we want to stick with to avoid moving the documentation around:

• Github Readme
• gircore/gir.core repository with a folder named "Documentation": I saw this lately on some projects. In this case the documentation is part of the code and is tagged with releases, etc.
• Separate repository (RFC): Much space for comprehensive documentation
• Homepage (is generated automatically from github repository with markdown). Is able to generate API documentation
• Github wiki

I want as less dobuled documentation as possible. Even know I don't like the duplication between the github readme and the homepage. The homepage is already out of date.

Are there any preferences or suggestions or missing things?

[mjakeman]

In my opinion:

• API Reference (Generated from Doc Comments): We generate this automatically from doc comments, using something like DocFX, and host the generated static site under the website (e.g. gircore.github.io/docs). This is relatively minimum effort, as once the foundations are in place we should be writing documented code anyway.
• User & Developer Docs (Website): This consists of everything other than the API Reference, and is stored under the website. This would include guides, tutorials, etc.

The RFCs repo would be a place for storing in-progress drafts for new features that are too complex to fit in a single issue (e.g. Type System Integration, where we will need to keep updating the proposal as we encounter problems). Once we implement a feature, we copy the relevant parts to the website repo, where it becomes part of our dev docs.

Even know I don't like the duplication between the github readme and the homepage.

I agree. I think the homepage should be the main user-facing page for the project, while the README is a collection of links to the website, documentation, plus very brief build instructions.

[badcel]

Okay so you do not want any documentation inside of the gir.core repository (except readme with links).

I would like to see if we could at least version our documentation along the release of the libraries. But I'm not sure if this is a must have feature.

Otherwise I'm okay with the approach to just put everything on the website.

[mjakeman]

I will try look into DocFX a bit more for this (it seems to be a good way to generate a C# API Reference)

Okay so you do not want any documentation inside of the gir.core repository (except readme with links).

I was mostly talking in terms of where it would be hosted. Ideally, all of our docs would fall under 'the website' in terms of a user accessing them. I don't mind where we store the docs themselves; I'd be quite happy with having them under the repo (we get the benefits of API versioning like you said), I'm just not sure we can do this with github pages?

[na2axl]

I would like to see if we could at least version our documentation along the release of the libraries. But I'm not sure if this is a must have feature.

I think it's always feasible by separating the documentation in another repo. We just have to create tags on the documentation repo each times the main repo get a new release. So an user which want to see the documentation of a specific release just have to switch to the right tag on the documentation repo.

I'm OK to the idea where all the documentation are in one place (our website), users are sometimes too lazy to browse between multiple places.

[mjakeman]

I think it's always feasible by separating the documentation in another repo

I know this is what gtk-rs does. They have a docs repo at gtk-rs/docs, so something similar could be an option for us.

[badcel]

I will try look into DocFX a bit more for this (it seems to be a good way to generate a C# API Reference)

I choose wyam as website generator because it can generate API documentation and a website. Perhaps it is easier to use this? GitHub.io repo is used for website generation. So changes to the develop branch will result in an automatic website regeneration.

[mjakeman]

Just had another look at wyam and apparently it's been "rebooted" as Statiq. According to wyam.io and the github page, wyam is effectively no longer being developed.

I've done some research into Statiq, and it is 'open-core' rather than FOSS (see here) and the whole licensing thing seems a bit iffy. It might be worth switching to a different static site generator. Thoughts? @badcel @na2axl

Edit: I've done some more digging and I haven't yet found anything comparable to wyam. I suppose the best option would be to use wyam for now and look towards migrating to a different generator in the future.

[badcel]

Oh i was not aware of the license change between wyam and statiq. When I last checked statiq did not seem to be ready for productive use.

Perhaps we are just going to use DocFX as the getting started and first steps reads like it could be used as a simple static site generator, too and it is MIT licensed.

[mjakeman]

Perhaps we are just going to use DocFX as the getting started and first steps reads like it could be used as a simple static site generator, too and it is MIT licensed.

I'll start looking into this. It seems like a simple option and it's backed by the dotnet team, so probably a safe bet. If we're not happy, we can always migrate to something else later, since all our docs would be markdown.

[mjakeman]

Made an initial port of the old website to DocFX and started generating an API Reference. There are lots of problems with the way I'm doing it now, but for a quick test you can see it at https://firox263.github.io/doc-test/index.html. The entire website is fairly rudimentary and the logo is just a colour swap of the official Gtk logo as a placeholder.

There are a few problems/decisions we need to address:

• Performance: DocFX is much, much slower than I'd like. It takes my laptop around 10 minutes to generate the metadata from scratch. Could be a CI burden? I think we can optimise this however - it is possible to run DocFX incrementally.
• In-tree vs out-of-tree docs: DocFX gives us the flexibility to store our docs either in this repo or a separate repo. In that case, I would suggest we keep our docs in the main repo to live alongside the source code.
• CI - I haven't yet figured out how to integrate this with a Build Server. It's definitely possible, but a bit more involved.
• Additional Metadata - We will want additional metadata for Signals, SignalArgs, Properties, etc. This might be possible with DocFX as-is, but otherwise writing a plugin would solve this.
• DocFX v3 - DocFX v3 is being worked on. It gains a host of improvements, but appears to break compatibility, so this current version could act as a stopgap for now.

Some actionable issues:

• Fix #90 for hiding struct methods
• Hide Native classes from DocFX (this might already be done - need to rebase)

[badcel]

@firox263 This looks very good :+1:

• Performance: I think it is not such a problem as it should be done by github actions. The current website is auto generated with this github action: GirCore Action
• In-tree vs out-of-tree docs: I think the docs could be in-tree but they would probably only be updated if there is a new release (push to master branch) or a manual update. I'm not sure how much time one run of the generation will take, but we have like 2000minutes / month with a time factor of 1 for a linux setup and a factor of 2 for windows.

I found this blog entry for a possible way to setup github actions: http://www.roji.org/docfx-with-github-actions

I don't know if there are better ways already, but it shows that it is at least possible.

[mjakeman]

Thanks! I will have a look into the link you sent about GitHub actions.

I'm thinking in order to minimise how much we use CI, we could tie our docs to a particular milestone like you suggested (where push to master=new stable ver). This way, each milestone/minor version has an API reference, but we don't regenerate the docs every commit (which would be wasteful).

With DocFX v3 this could very well change (as this is what powers Microsoft's own docs.microsoft.com website), and it might be more CI friendly. I suppose we'll have to wait and see.

W.r.t. how we structure the API reference, it could be worth looking into a plugin/addon of sorts for DocFX to properly categorise Signals and Properties, and also remove SignalArgs from cluttering the sidebar.

[badcel]

The author of scriban is working on lunet which is a static website generator which is under development. I did not look into it, but if it will be comparable to scriban qualitywise this could be a very good product and should be definetly on our radar.

[badcel]

NuDoq is a library which allows to parse the doc comments of assemblies. With this we could relatively easy generate some markdown documentation

[badcel]

XmlDocMarkdown Looks very promising, too.

[badcel]

If we merge #212 I would like to test github pages with jekyl as a replacement for Wyam. We can checkout the code on push to develop branch and generate documentation and then publish automatically to master. Alternatively we can trigger the workflow manually.

[badcel]

Jekyll did not work out as it was by far to slow for our API. It took more than ten minutes to generate which results in an github timeout (~14k files).

I switched to Hugo (written in go) and the website is online. There are still some broken links or missing things like the logo but all in all it is working.

What do you think @gircore/coreteam ? I would close this issue if Hugo is the way to go with our documentation / website.

To change the website a push to develop in the homepage repo or manual trigger of the workflow is sufficient to update the page.

[badcel]

Today I updated the homepage and I think it can stay like it is for now. There is an API documentation which reveals that our API is not very polished yet but this is expected as we are not hiding all the low level c structs etc.

The homepage is updating onece per week automatically. If there are any issues please report.