Migrate to different structure, markup, validation, and/or host

[thorehusfeldt]

Over the past few days, I have edited a parallel document to the specification hosted here. You can check it out at

• https://problem-package-format-copy.readthedocs.io/en/latest/
• Sources: https://github.com/thorehusfeldt/problem_package_format_copy

How it differs

1. Document structure. I use a very different approach to document structure. In particular, section 1 contains everything you need for a simple pass-fail problem; all other concepts are in separate, later sections
2. Stringency. My prose, schemas, terminology, stance, etc. are much more stringent than what we have here. This ambition is not yet completely done, there are several sections (output validation) that I haven’t touched at all. But other sections (like 2. Problem Settings) hint at where I want to go.
3. Running, complete examples. There is an example problem package, increment in /problems/increment that is included piecemeal in the documentation. There should be more of those (in particular, a scoring problem, but maybe also an interactive problem and a custom pass-fail output validator.)
4. Validation. The script test.sh validates much of the yaml in the repo against the schemas. There could be more of this (all yaml should be validated, and ideally the complete example problems should be verifyproblemed. This is all doable and easy).
5. Layout. I’m using ReStructuredText (RST) instead of Markdown, which allows much better results. Check again, if you’d like, Section 3: Problem Settings.
6. Hosting. The documentation is hosted at ReadTheDocs, which takes care of many things (in particular the build process, but also versioning). This is an extremely pleasant experience for me as a maintainer, but also results in a dependable place to access the documentation. I believe in this.

How to migrate

I strongly suggest to migrate the documentation in the direction of my suggestion. There are a number of ways to do that

1. Merge. Merge Thore’s repo into the Kattis repo. It‘s not much of a merge – almost every file is completely new or entirely rewritten, so there won’t be useful diffs.
2. Abandon. Github user Kattis starts a fresh repo, forking Thore’s. (Or checking out Thore’s current commit as a first commit – I have no opinion on this.)

Moreover,

a. We let a github build script render the RST. See https://www.sphinx-doc.org/en/master/tutorial/deploying.html . I have no experience with this but trust that it’s quite easy.
b. We host using Build the Docs. For this, Github user Kattis needs to get a Read the docs account.

I am for 2b but have no strong opinion. But a decision about these choices is important for how to proceed.

[niemela]

I am for 2b but have no strong opinion. But a decision about these choices is important for how to proceed.

I would prefer 1b. It's true that it does not give us useful diffs, but it will keep the history, and I think that's worthwhile. I'll be setting up a paid account so we can skip the ads...

[thorehusfeldt]

1b is great.

You can checkout my repo (or tell me if you want to become admin on it) and do with it what you want. (Preserving history of that repo is not important.)

If development of the problem package format documentation then continues on Github User Kattis’s repo, I humbly request write access to it.

[niemela]

I humbly request write access to it.

You have write access now.

[thorehusfeldt]

@niemela : I think you have the ball on migrating to the contents on my fork.

(In particular, it involves setting up a readthedocs-account for the “Kattis” user/organisation/animal, so I can’t do this.)

Let me know how I can help.