Online documentation

[mcarans]

I have set up the framework for online documentation: https://oolite.readthedocs.io/en/latest/

I experimented with MkDocs and Sphinx DOxygen integrations but none worked completely, so decided on linking directly to DOxygen generated HTML from MkDocs. I updated DOxygen so that like MkDocs, it uses a Material theme with a toggle for light/dark mode. The API Reference link goes to the DOxygen API docs.

Next job will be to decide what goes in these documents and to add more markdown pages here: https://github.com/mcarans/oolite/tree/ ... ation/docs

[mcarans]

Converting the reference sheet to markdown didn't work very well. I've managed to embed the reference sheet as a pdf here: https://oolite.readthedocs.io/en/latest/reference/

[another_commander]

The reference sheet mentions Mac keys and the readme pdf contains references to Mac. These need to be removed for 1.92.

I also have to point out that the PDFs included in the installers for Windows are still the wrong ones and have the "outdated" watermark on them. I think I'll just go ahead and replace those PDFs with the actual current ones, can't see any other way to fix this.

[mcarans]

The reference sheet mentions Mac keys and the readme pdf contains references to Mac. These need to be removed for 1.92.

I also have to point out that the PDFs included in the installers for Windows are still the wrong ones and have the "outdated" watermark on them. I think I'll just go ahead and replace those PDFs with the actual current ones, can't see any other way to fix this.

Do you mean on my master branch (in which case that is because I have removed steps from the build_all in preparation for the new readthedocs) or on the Oolite main repository master (where I though I had added the step back for Windows that unarchives the generated docs)?

[another_commander]

Do you mean on my master branch (in which case that is because I have removed steps from the build_all in preparation for the new readthedocs) or on the Oolite main repository master (where I though I had added the step back for Windows that unarchives the generated docs)?

I mean the main Oolite repository master. I'm thinking of just generating up-to-date PDFs from the LibreOffice docs so that those PDFs will be included in the github actions builds instead of the dummy ones. Unless there is a way to auto-generate the PDFs during build and include them in the final installers.

I am not convinced that the automatically versioned PDFs are really useful, given that we only change them once every three years or so. Removing the auto-generation from the github actions build could make the workflow simpler, too. But if there is a way to make the right PDFs end up in the build - automated or not - I'd be fine with it.

[mcarans]

Do you mean on my master branch (in which case that is because I have removed steps from the build_all in preparation for the new readthedocs) or on the Oolite main repository master (where I though I had added the step back for Windows that unarchives the generated docs)?

I mean the main Oolite repository master. I'm thinking of just generating up-to-date PDFs from the LibreOffice docs so that those PDFs will be included in the github actions builds instead of the dummy ones. Unless there is a way to auto-generate the PDFs during build and include them in the final installers.

I am not convinced that the automatically versioned PDFs are really useful, given that we only change them once every three years or so. Removing the auto-generation from the github actions build could make the workflow simpler, too. But if there is a way to make the right PDFs end up in the build - automated or not - I'd be fine with it.

Ok got it. I'm not sure why that is happening. I have already removed the version from the reference sheet in my fork and cleaned up the footer. I have now removed the Mac keys and done a major clean up of the formatting which was difficult. I have also managed to get it to display much larger which looks much better: https://oolite.readthedocs.io/en/latest/reference/

In my branch, I have already removed the step to generate the documents. I think it easier to just generate a new PDF and check in when updating the LibreOffice documents.

Having said that, will the PDFs still be needed if all the content in those PDFs is in readthedocs? It would be easier to just point to the readthedocs site and it would avoid having 2 sources to update (since other than the reference sheet PDF, the other pages in readthedocs will be markdown).

[phkb]

It's probably not a huge issue, but when I look at the existing ODT file in LibreOffice, there are only 9 pages, not 11. The "Game Settings" section fits into one column (not 2), and the "Joystick Flight Controls" + "Mouse Flight Controls" are in 3 columns (not 4). Those things are pushing out the number of pages.

[another_commander]

Having said that, will the PDFs still be needed if all the content in those PDFs is in readthedocs? It would be easier to just point to the readthedocs site and it would avoid having 2 sources to update (since other than the reference sheet PDF, the other pages in readthedocs will be markdown).

I was just thinking that, in the interests of not delaying the next release, maybe we can have the PDFs included for 1.92 and switch to the external source after that, giving us all the time we need to prepare the readthedocs space as we see fit.

The source documentation files (.odts) should be kept in the repository anyway and maintained, in my opinion. They are the source material needed for any potential updates, including any docs put up on readthedocs. This is especially true for the Ref Sheet and the Readme.

While we are at it, can I ask for a favor? The MS Store requires a privacy policy URL amongst other stuff and since you are building up readthedocs I was wondering if it would be possible to add one more page, titled Oolite - Privacy Policy and include this text (html format, maybe needs conversion to markdown):

Code: Select all

<section>
    <h1>Privacy Policy for Oolite</h1>
    <p><strong>Last Updated: January 22, 2026</strong></p>
</section>
<section>
    <h2>1. Introduction</h2>
    <p>This Privacy Policy explains how Oolite (https://oolite.space) collects, uses, and protects your information when you use our services. We are committed to safeguarding your privacy and ensuring that your personal information is handled responsibly and in accordance with applicable laws, including the General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA).</p>
</section>
<section>
    <h2>2. Information Collection</h2>
    <p>Oolite does not collect any personal information from its users. We are dedicated to providing a service that respects the privacy of our users by ensuring that no identifiable personal data is gathered during your use of our application.</p>
</section>
<section>
    <h2>3. Use of Information</h2>
    <p>Since we do not collect personal information, we do not use it for any purposes. Our application is designed to operate without the need for your personal data, allowing you to use our services freely and without concerns about your privacy.</p>
</section>
<section>
    <h2>4. Information Sharing</h2>
    <p>As we do not collect personal information, we do not share any data with third parties. Your privacy is important to us, and we ensure that no information is sold, traded, or otherwise disclosed to any outside parties.</p>
</section>
<section>
    <h2>5. Data Storage and Security</h2>
    <p>Since we do not collect personal information, there is no data to store. However, we implement appropriate security measures to protect the integrity of our application and to maintain the privacy of our users.</p>
</section>
<section>
    <h2>6. User Rights</h2>
    <p>As we do not collect personal data, there are no rights regarding access, deletion, or modification of such data. Users are free to use our application without any obligations regarding personal information.</p>
</section>
<section>
    <h2>7. Cookies and Tracking</h2>
    <p>Oolite does not utilize cookies or tracking technologies to monitor user activity. Our application operates without the need for tracking user behavior or storing data that could identify you.</p>
</section>
<section>
    <h2>8. Children's Privacy</h2>
    <p>Oolite does not collect any information from its users, including children under the age of 13. However, if we ever become aware that we have inadvertently collected personal data from a child, we will take steps to delete such information as quickly as possible.</p>
</section>
<section>
    <h2>9. Changes to Privacy Policy</h2>
    <p>We may update this Privacy Policy from time to time to reflect changes in our practices or for other operational, legal, or regulatory reasons. We encourage you to review this policy periodically for the latest information on our privacy practices.</p>
</section>
<section>
    <h2>10. Contact Information</h2>
    <p>If you have any questions or concerns regarding this Privacy Policy or our practices, please contact us by visiting the Oolite forum at <a href="https://bb.oolite.space">https://bb.oolite.space</a>.</p>
</section>
<section>
    <h2>Conclusion</h2>
    <p>Your privacy is important to us. By using Oolite, you can be assured that we prioritize your privacy and do not collect any personal information. We are committed to maintaining a transparent and secure environment for our users.</p>
</section>

Note: I am no legal expert, this was generated by AI and I have already modified it slightly to fit our case. If there are any comments or changes to propose, feel free.

[hiran]

...

I am not convinced that the automatically versioned PDFs are really useful, given that we only change them once every three years or so. Removing the auto-generation from the github actions build could make the workflow simpler, too. But if there is a way to make the right PDFs end up in the build - automated or not - I'd be fine with it.

...
In my branch, I have already removed the step to generate the documents. I think it easier to just generate a new PDF and check in when updating the LibreOffice documents.

That is interesting. I changed from that behaviour as more than once the docs and the pdfs were not updated in sync. Also using different rendering engines can give slightly different results when it comes to layout/page breaks/line breaks.

Thus a developer would simply have to update the odt, the rest would be automatic. Also for users it would just take a moment to check the version on the page to tell if they are looking at the correct documentation.

Let's see how it works out with readthedocs.

[another_commander]

That is interesting. I changed from that behaviour as more than once the docs and the pdfs were not updated in sync.

They don't have to be updated in sync. The only time they need to be synced is just before release. Every two or three years (or 5+ in our case).

Thus a developer would simply have to update the odt, the rest would be automatic. Also for users it would just take a moment to check the version on the page to tell if they are looking at the correct documentation.

Perfectly ok with that, provided that it works. The problem is that it currently doesn't work. Either it gets fixed to work, or it gets reverted to the past state.

[mcarans]

It's probably not a huge issue, but when I look at the existing ODT file in LibreOffice, there are only 9 pages, not 11. The "Game Settings" section fits into one column (not 2), and the "Joystick Flight Controls" + "Mouse Flight Controls" are in 3 columns (not 4). Those things are pushing out the number of pages.

When I load the original odt (https://github.com/OoliteProject/oolite ... liteRS.odt) in LibreOffice, it is 16 pages and the formatting is a mess. Is that what you see? It is that mess that I have been trying to fix. If that is not what you see, then it means that two versions of LibreOffice cannot load the same document and display it the same way.

I can see the PDF (https://github.com/OoliteProject/oolite ... liteRS.pdf) is 9 pages, but it is outdated lacking things like "HDR Max Brightness (nits) - value".

I'll try to have a look at what is happening with the Windows build. I had added back the step to unarchive the built documentation in the workflow so not sure why it isn't being picked up.

[another_commander]

When I load the original odt (https://github.com/OoliteProject/oolite ... liteRS.odt) in LibreOffice, it is 16 pages and the formatting is a mess. Is that what you see? It is that mess that I have been trying to fix. If that is not what you see, then it means that two versions of LibreOffice cannot load the same document and display it the same way.

For me the OoliteRS.odt is 9 pages with good formatting. My LibreOffice Writer version is 7.4.3.2.

[mcarans]

When I load the original odt (https://github.com/OoliteProject/oolite ... liteRS.odt) in LibreOffice, it is 16 pages and the formatting is a mess. Is that what you see? It is that mess that I have been trying to fix. If that is not what you see, then it means that two versions of LibreOffice cannot load the same document and display it the same way.

For me the OoliteRS.odt is 9 pages with good formatting. My LibreOffice Writer version is 7.4.3.2.

Hmm, my version is the default in my distro:

Version: 25.8.3.2 (X86_64) / LibreOffice Community
Ubuntu package version: 4:25.8.3-0ubuntu0.25.10.1

This means that odt is not a consistent format which is surprising and disappointing. I thought this kind of issue was a problem of word processors of the past. That means that only certain individuals will be able to update that odt and then only as long as they never update LibreOffice! Not a recipe for a collaborative open source project.

Presumably if you load my 10 page version that looks ok on my system (https://github.com/mcarans/oolite/blob/ ... liteRS.odt), it is a mess for you? Sometimes even reloading what I just saved changes the formatting, although now I think the odt I have made is at least stable on my own machine.

[another_commander]

I'll check and get back to you in a few hours. I have shut down for tonight - late night here and early wake up tomorrow...

[hiran]

When I load the original odt (https://github.com/OoliteProject/oolite ... liteRS.odt) in LibreOffice, it is 16 pages and the formatting is a mess. Is that what you see? It is that mess that I have been trying to fix. If that is not what you see, then it means that two versions of LibreOffice cannot load the same document and display it the same way.

For me the OoliteRS.odt is 9 pages with good formatting. My LibreOffice Writer version is 7.4.3.2.

Hmm, my version is the default in my distro:

Version: 25.8.3.2 (X86_64) / LibreOffice Community
Ubuntu package version: 4:25.8.3-0ubuntu0.25.10.1

This means that odt is not a consistent format which is surprising and disappointing. I thought this kind of issue was a problem of word processors of the past. That means that only certain individuals will be able to update that odt and then only as long as they never update LibreOffice! Not a recipe for a collaborative open source project.

Presumably if you load my 10 page version that looks ok on my system (https://github.com/mcarans/oolite/blob/ ... liteRS.odt), it is a mess for you?

Did you check whether you have the the Microsoft Fonts installed? For Ubuntu they come in an extra package.