Update and create readmes so that the app docs create a consistent ta…

…ble (sio2project#196)
gkju · Apr 24, 2023 · df72e00 · df72e00
1 parent 2952137
commit df72e00
Show file tree

Hide file tree

Showing 59 changed files with 121 additions and 98 deletions.
diff --git a/oioioi/amppz/README.rst b/oioioi/amppz/README.rst
@@ -1,3 +1 @@
-This module is responsible for handling one of Polish programming contests
--- Akademickie Mistrzostawa Polski w Programowaniu Zespołowym
-(see contest website: http://amppz.mimuw.edu.pl/).
+Handles `Akademickie Mistrzostwa Polski w Programowaniu Zespołowym type <http://amppz.mimuw.edu.pl/>`_ programming contests.
diff --git a/oioioi/analytics/README.rst b/oioioi/analytics/README.rst
@@ -1 +1 @@
-This module adds support for Google Analytics.
+Google Analytics.
diff --git a/oioioi/balloons/README.rst b/oioioi/balloons/README.rst
@@ -1,2 +1 @@
-This module provides an interface for supporting teams delivering balloons
-during ACM contest.
+An interface for supporting teams delivering balloons during ACM contests.
diff --git a/oioioi/celery/README.rst b/oioioi/celery/README.rst
@@ -1,2 +1,2 @@
-This module takes care of proper initialization of Celery -
-Distributed Task Queue for judging submissions.
+Proper initialization of Celery --
+the Distributed Task Queue for judging submissions.
diff --git a/oioioi/clock/README.rst b/oioioi/clock/README.rst
@@ -1 +1 @@
-A module with current time and countdown clock implementation.
+Display current time and countdown in the navbar.
diff --git a/oioioi/complaints/README.rst b/oioioi/complaints/README.rst
@@ -1 +1 @@
-A module for sending complaints from participants to jury.
+Complaints from participants to the jury.
diff --git a/oioioi/confirmations/README.rst b/oioioi/confirmations/README.rst
@@ -1,2 +1,2 @@
-This module is responsible for sending e-mail confirmations
+Sending e-mail confirmations
 after participant's submission during a contest.
diff --git a/oioioi/contestexcl/README.rst b/oioioi/contestexcl/README.rst
@@ -1,2 +1,2 @@
-This module adds a possibility of creating an exclusive contest
--- its users cannot enter any other contests.
+Exclusive contests
+(its users cannot enter any other contests).
diff --git a/oioioi/contestlogo/README.rst b/oioioi/contestlogo/README.rst
@@ -1 +1 @@
-A module responsible for displaying a logo for a contest.
+Displays the contest logo.
diff --git a/oioioi/contests/README.rst b/oioioi/contests/README.rst
@@ -1,4 +1,4 @@
-This huge module implements top-level logic connected with all contests:
+Top-level logic connected with all contests:
 problem instance, submission, score report, user results,
 round time extension, judge process, user registration,
 rendering reports and more.
diff --git a/oioioi/dashboard/README.rst b/oioioi/dashboard/README.rst
@@ -1 +1 @@
-A module implementing contest dashboard.
+Implements the contest dashboard.
diff --git a/oioioi/deployment/README.rst b/oioioi/deployment/README.rst
@@ -1,2 +1,2 @@
-This module contains templates for a Django deployment - manage.py, settings.py
-and other similar.
+Contains templates for a Django deployment -- manage.py, settings.py,
+and similar.
diff --git a/oioioi/disqualification/README.rst b/oioioi/disqualification/README.rst
@@ -0,0 +1,2 @@
+
+Contestant disqualifications.
diff --git a/oioioi/evalmgr/README.rst b/oioioi/evalmgr/README.rst
@@ -1,6 +1,8 @@
-Evaluation Manager is a module taking a recipe along with parameters
-in 'env' variable (large dictionary) and processing it according to
-a recipe. This process is used to compile, execute and grade
+Takes a recipe along with parameters
+in 'env' variable (a large dictionary), and processes it according to
+the recipe.
+
+This process is used to compile, execute and grade
 submissions in a programming contest. This module adds a visual
-interface to it's queue as well, allowing to view and remove
+interface to its queue as well, to allow viewing and removing
 pending submissions.
diff --git a/oioioi/filetracker/README.rst b/oioioi/filetracker/README.rst
@@ -1,2 +1,2 @@
-Filetracker is a module for storing files like submission
-source codes and tests.
+Stores files (submission
+source codes, tests, etc.).
diff --git a/oioioi/forum/README.rst b/oioioi/forum/README.rst
@@ -1 +1 @@
-This module is responsible for a contest forum.
+Adds contest forums.
diff --git a/oioioi/globalmessage/README.rst b/oioioi/globalmessage/README.rst
@@ -1,6 +1,6 @@
-An optional module for showing alert for all users on every page, for example
+An optional module. Shows alerts for all users on every page, for example
 to announce planned downtime or current system issues.
 
 There can be one message at most.
 
-Message can be programmed to automatically show and hide at given times.
+Message can be programmed to automatically show and hide at given times.
diff --git a/oioioi/ipauthsync/README.rst b/oioioi/ipauthsync/README.rst
@@ -0,0 +1 @@
+Validating incoming IP addresses.
diff --git a/oioioi/ipdnsauth/README.rst b/oioioi/ipdnsauth/README.rst
@@ -1 +1 @@
-A module implementing authentication based on user IP or DNS hostname.
+Authentication based on user IP or DNS hostname.
diff --git a/oioioi/livedata/README.rst b/oioioi/livedata/README.rst
@@ -0,0 +1 @@
+Endpoints to query live data about tasks, submission events and teams.
diff --git a/oioioi/liveranking/README.rst b/oioioi/liveranking/README.rst
@@ -0,0 +1 @@
+Endpoints to query live data about submissions.
diff --git a/oioioi/mailsubmit/README.rst b/oioioi/mailsubmit/README.rst
@@ -0,0 +1 @@
+Handle postal submissions.
diff --git a/oioioi/maintenancemode/README.rst b/oioioi/maintenancemode/README.rst
@@ -0,0 +1,2 @@
+
+Allow putting the site into maintenance mode, where all functionality is disabled. ("Sorry, the site is under maintenance.")
diff --git a/oioioi/mp/README.rst b/oioioi/mp/README.rst
@@ -1,2 +1,2 @@
-This module is responsible for handling Mistrz Programowania programming contests
-(see 2022 contest website: https://oki.org.pl/mistrz-programowania-2022/).
+Supports Mistrz Programowania type contests
+(`2022 contest website <https://oki.org.pl/mistrz-programowania-2022/>`_).
diff --git a/oioioi/newsfeed/README.rst b/oioioi/newsfeed/README.rst
@@ -1,4 +1,3 @@
-This module adds newsfeed feature. Additionaly, it adds
-single news and newsfeed widgets to portals.
+Adds the newsfeed, single news, and newsfeed widgets to portals.
 
-It requires portals app to be enabled.
+The portals app must be enabled.
diff --git a/oioioi/oi/README.rst b/oioioi/oi/README.rst
@@ -1,2 +1,2 @@
-This module is responsible for handling Polish Olympiad type
-programming contests. (see contest web site: http://oi.edu.pl/)
+Support for `Polish Olympiad type <http://oi.edu.pl/>`_
+programming contests.
diff --git a/oioioi/oireports/README.rst b/oioioi/oireports/README.rst
@@ -1 +1 @@
-A module implementing the HTML, PDF and XML report logic.
+HTML, PDF and XML reports.
diff --git a/oioioi/oisubmit/README.rst b/oioioi/oisubmit/README.rst
@@ -1,3 +1,3 @@
-This module provides some utils for submissions during the
-Polish Olympiad in Informatics, helping to find suspected submissions
-like submitted before the contest start.
+Provides some utils for submissions during the
+Polish Olympiad in Informatics, helping to find suspicious submissions
+(like these submitted before the contest start).
diff --git a/oioioi/pa/README.rst b/oioioi/pa/README.rst
@@ -1,3 +1,2 @@
-This module is responsible for handling one of Polish programming contests
--- Potyczki Algorytmiczne
-(see contest website: http://potyczki.mimuw.edu.pl/).
+Support for one of Polish programming contests
+-- `Potyczki Algorytmiczne <http://potyczki.mimuw.edu.pl/>`_.
diff --git a/oioioi/participants/README.rst b/oioioi/participants/README.rst
@@ -1 +1 @@
-This module is responsible for contest's participants registration.
+Contest's participants registration.
diff --git a/oioioi/plagiarism/README.rst b/oioioi/plagiarism/README.rst
@@ -1,2 +1,2 @@
-This module contains tools for plagiarism detection among contest submissions.
+Tools for plagiarism detection among contest submissions.
 Currently there is only a contest admin tab for exporting source codes to the MOSS system.
diff --git a/oioioi/portals/README.rst b/oioioi/portals/README.rst
@@ -0,0 +1,2 @@
+
+Adds portals -- pages where users can write their own content.
diff --git a/oioioi/printing/README.rst b/oioioi/printing/README.rst
@@ -1 +1 @@
-This module allows contestants to print text files (eg. source code).
+Allows contestants to print text files (eg. source code).
diff --git a/oioioi/problemsharing/README.rst b/oioioi/problemsharing/README.rst
@@ -2,11 +2,8 @@
 Problem Sharing
 ===============
 
-Description
-===========
-
-Problem sharing module allows to share problems.
-Currently only way of sharing is through a one-sided friendship.
+Allows teachers to share problems.
+Currently the only way to share is through a one-sided friendship.
 
 Activating this module adds:
 

diff --git a/oioioi/publicsolutions/README.rst b/oioioi/publicsolutions/README.rst
@@ -1 +1 @@
-A module implementing publishing and viewing participants' solutions.
+Publishing and viewing participants' solutions.
diff --git a/oioioi/questions/README.rst b/oioioi/questions/README.rst
@@ -1,2 +1,2 @@
-This module provides questions and answers system for
+Questions and answers system for
 contestants during a contest.
diff --git a/oioioi/quizzes/README.rst b/oioioi/quizzes/README.rst
@@ -0,0 +1 @@
+Adds problems which are quizzes.
diff --git a/oioioi/rankings/README.rst b/oioioi/rankings/README.rst
@@ -1 +1 @@
-A module implementing html and cvs ranking views.
+HTML and CSV ranking views.
diff --git a/oioioi/scoresreveal/README.rst b/oioioi/scoresreveal/README.rst
@@ -1,3 +1,4 @@
-This module implements score revealing. Participants are provided
-with some number of tokens for each task.
+Score revealing.
+
+Participants are provided with some number of tokens for each task.
 Tokens can be used for revealing scores for specified submissions.
diff --git a/oioioi/similarsubmits/README.rst b/oioioi/similarsubmits/README.rst
@@ -0,0 +1 @@
+Allows the organisers to mark submissions as similar, and displays this to participants.
diff --git a/oioioi/simpleui/README.rst b/oioioi/simpleui/README.rst
@@ -1,3 +1,3 @@
-This module is a set of simplified templates/views for users.
-It provides sites like user or contest dashboards.
-It can be used by many separate apps, just make sure there are no conflicts.
+A set of simplified templates/views for users.
+Provides sites like user or contest dashboards.
+Can be used by many separate apps, just make sure there are no conflicts.
diff --git a/oioioi/sinolpack/README.rst b/oioioi/sinolpack/README.rst
@@ -1,5 +1,5 @@
-This module is responsible for handling
-Sinol packages - standardized archives with problem data.
+Support for
+Sinol packages -- standardized archives with problem data.
 Sinolpack is OIOIOI standard problem package format.
 The detailed archive content description can be found here:
 https://github.com/sio2project/oioioi/wiki
diff --git a/oioioi/sioworkers/README.rst b/oioioi/sioworkers/README.rst
@@ -1,2 +1,2 @@
-A module containing front-end code for sioworkers,
-used for staring their jobs.
+Front-end code for sioworkers,
+used for starting their jobs.
diff --git a/oioioi/statistics/README.rst b/oioioi/statistics/README.rst
@@ -1 +1 @@
-A module providing contest statistics for admins and participants.
+Contest statistics for admins and participants.
diff --git a/oioioi/status/README.rst b/oioioi/status/README.rst
@@ -1,2 +1,2 @@
-A module containing small framework used for automatic update
-of some interface parts, like time synchronization (every 5 minutes).
+Small framework used for automatic update
+of some parts of the UI, like time synchronization (every 5 minutes).
diff --git a/oioioi/su/README.rst b/oioioi/su/README.rst
@@ -1,2 +1,2 @@
-This module adds an option for admins to log in as other user
+An option for admins to log in as other user
 for testing purposes.
diff --git a/oioioi/submitservice/README.rst b/oioioi/submitservice/README.rst
@@ -1 +1 @@
-A module that enables automated solution submitting from user's terminal.
+Automated solution submitting from user's terminal.
diff --git a/oioioi/suspendjudge/README.rst b/oioioi/suspendjudge/README.rst
@@ -1 +1 @@
-This module adds an option to suspend judging of selected problems.
+Adds an option to suspend judging of selected problems.
diff --git a/oioioi/szkopul/README.rst b/oioioi/szkopul/README.rst
@@ -0,0 +1 @@
+Custom functionality for the `Szkopuł <https://szkopul.edu.pl>`_ platform.
diff --git a/oioioi/teachers/README.rst b/oioioi/teachers/README.rst
@@ -1,2 +1,2 @@
-This module adds an option to create and administrate
+Adds an option to create and administer
 a new contest by teachers.
diff --git a/oioioi/teams/README.rst b/oioioi/teams/README.rst
@@ -1 +1 @@
-A module providing features for team-based contests.
+Features for team-based contests.
diff --git a/oioioi/testrun/README.rst b/oioioi/testrun/README.rst
@@ -1 +1 @@
-A module that allows to execute a program in conditions similar to the final checking.
+Allows to execute a program in conditions similar to the final checking.
diff --git a/oioioi/testspackages/README.rst b/oioioi/testspackages/README.rst
@@ -1,7 +1,7 @@
 Testspackages
 ~~~~~~~~~~~~~
 
-This module allows users to publish the tests for packages in the contest.
+Allows users to publish the tests for packages in the contest.
 If the problem is public, in problemset there will be an additional tab where
 zipped tests can be downloaded.
 
@@ -12,9 +12,9 @@ First, make sure you are the owner of package. It's not possible to publish
 tests for package added from external source -- e.g. problemset.
 It's because test package is connected to problem, not the probleminstance.
 
-Assuming you are the owner of the package, find the problem for which you want to publish the tests.
-In the contest view, go to "Problems" in "Contest Administration" tab and then click "Advanced settings"
-next to the chosen problem. Now, in "Tests Packages" form you can specify which test cases you want to publish
-and specify the publish date. It's also possible to customize file name and description.
+#. Assuming you are the owner of the package, find the problem for which you want to publish the tests.
+#. In the contest view, go to "Problems" in "Contest Administration" tab and then click "Advanced settings"
+#. next to the chosen problem. Now, in "Tests Packages" form you can specify which test cases you want to publish
+#. and specify the publish date. It's also possible to customize file name and description.
 
 After the publish date tests will be visible for ALL participants in the contest.
diff --git a/oioioi/timeline/README.rst b/oioioi/timeline/README.rst
@@ -1,2 +1,2 @@
-A module implementing the admin timeline view,
+Implements the admin timeline view,
 used for manipulating contest's dates.
diff --git a/oioioi/usercontests/README.rst b/oioioi/usercontests/README.rst
@@ -1,2 +1,2 @@
-This module enables every regular user to create and admin their own contests.
-It is an experimental feature - use at your own risk!
+Enables every regular user to create and administer their own contests.
+It is an experimental feature -- use at your own risk!
diff --git a/oioioi/usergroups/README.rst b/oioioi/usergroups/README.rst
@@ -1 +1 @@
-This module adds an option to group selected users into personal user groups and share them with other teachers.
+Adds an option to group selected users into personal user groups and share them with other teachers.
diff --git a/oioioi/workers/README.rst b/oioioi/workers/README.rst
@@ -0,0 +1 @@
+Displays running workers (useful mainly for system admins).
diff --git a/rst/Makefile b/rst/Makefile
@@ -36,7 +36,7 @@ clean:
 	-rm -rf $(BUILDDIR)/*
 
 autogen:
-	python gendoc.py
+	python3 gendoc.py
 
 html: autogen
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

diff --git a/rst/gendoc.py b/rst/gendoc.py
@@ -16,37 +16,51 @@
 sections_suff = '../rst/source/sections/'
 sections_dist = len(sections_suff.split(os.sep))
 
-entries = []
-
-entries.append(
-    """
-Autogenerated by the /rst/gendoc.py script
+entries = ["""
+..
+   Autogenerated by the /rst/gendoc.py script
 
 ==============
 OIOIOI Modules
 ==============
 
-List of modules
----------------
-
-"""
-)
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Module
+     - Implements
+
+"""]
+missing = []
 
 oioioi_dirname = os.path.dirname(oioioi.__file__)
 sections_dirname = os.path.join(oioioi_dirname, sections_suff)
 for root, dirs, files in os.walk(oioioi_dirname):
     dirs.sort()
     rel_root = os.path.relpath(root, sections_dirname)
-    module_name = '.'.join(rel_root.split(os.sep)[sections_dist - 1 :])
-    if 'README.rst' in files:
-        entries.append(
-            '**%s**\n\n.. include:: %s/README.rst\n\n' % (module_name, rel_root)
-        )
-    elif len(rel_root.split(os.sep)) == sections_dist and 'locale' not in module_name:
-        print("No README.rst in %s" % module_name)
+    module_name = '.'.join(rel_root.split(os.sep)[sections_dist - 1:])
+
+    if "." in module_name or module_name.startswith("_") or not module_name:
+        continue
+
+    include_readme = f".. include:: {rel_root}/README.rst"
+    if 'README.rst' not in files:
+        include_readme = "*README.rst missing*"
+        missing.append(module_name)
+
+    entries.append(
+        f"   * - {module_name}\n"
+        f"     - {include_readme}\n"
+    )
 
 content = ''.join(entries)
 
+if missing:
+    print(sys.stderr, "Some README.rst for modules are missing:", missing)
+
+
+
 if len(sys.argv) > 1 and (sys.argv[1] == '--verbose' or sys.argv[1] == '-v'):
     print(content)
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		This module adds support for Google Analytics.
		Google Analytics.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		A module with current time and countdown clock implementation.
		Display current time and countdown in the navbar.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		A module for sending complaints from participants to jury.
		Complaints from participants to the jury.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		A module responsible for displaying a logo for a contest.
		Displays the contest logo.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		A module implementing contest dashboard.
		Implements the contest dashboard.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		This module is responsible for a contest forum.
		Adds contest forums.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		A module implementing authentication based on user IP or DNS hostname.
		Authentication based on user IP or DNS hostname.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Endpoints to query live data about tasks, submission events and teams.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Endpoints to query live data about submissions.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@

		Allow putting the site into maintenance mode, where all functionality is disabled. ("Sorry, the site is under maintenance.")