Skip to content
This repository was archived by the owner on May 1, 2024. It is now read-only.

Commit fca3c63

Browse files
feanilfeanil
authored
Merge pull request #472 from edx/feanil/fix_docs
Feanil/fix docs
2 parents 3166815 + 65d5e42 commit fca3c63

10 files changed

Lines changed: 185 additions & 103 deletions

File tree

‎.readthedocs.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# .readthedocs.yml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required: the version of this file's schema.
6+
version: 2
7+
8+
# Build documentation in the docs/ directory with Sphinx
9+
sphinx:
10+
configuration: docs/api/source/conf.py
11+
12+
# Optionally set the version of Python and requirements required to build your docs
13+
python:
14+
version: "3.8"
15+
install:
16+
- requirements: requirements/doc.txt

‎.travis.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ matrix:
2424
after_success:
2525
- docker exec analytics_api_testing /edx/app/analytics_api/analytics_api/.travis/run_coverage.sh
2626
- codecov --disable pycov
27+
- python: '3.8'
28+
env: TESTNAME=docs TARGETS="docs"
2729
env:
2830
global:
2931
- DOCKER_USERNAME=edxbuilder

‎Makefile‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ help: ## display this help message
1010
@echo "Please use \`make <target>' where <target> is one of"
1111
@perl -nle'print $& if m{^[\.a-zA-Z_-]+:.*?## .*$$}' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m %-25s\033[0m %s\n", $$1, $$2}'
1212

13-
.PHONY: requirements develop clean diff.report view.diff.report quality static
13+
.PHONY: requirements develop clean diff.report view.diff.report quality static docs
1414

1515
requirements: ## install base requirements
1616
pip3 install -q -r requirements/base.txt
@@ -144,3 +144,7 @@ travis_docker_push: travis_docker_tag travis_docker_auth ## push to docker hub
144144
docker push "openedx/analytics-data-api:$$TRAVIS_COMMIT"
145145
docker push 'openedx/analytics-data-api:latest-newrelic'
146146
docker push "openedx/analytics-data-api:$$TRAVIS_COMMIT-newrelic"
147+
148+
docs:
149+
pip install -r requirements/tox.txt
150+
tox -e docs

‎docs/api/source/conf.py‎

Lines changed: 26 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
import os
22
import sys
3+
import django
34

4-
from path import path
5+
from path import Path
56

6-
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
7-
8-
# sys.path.insert(0, os.path.abspath('..'))
7+
import edx_theme
98

109
# Add any paths that contain templates here, relative to this directory.
1110
# templates_path.append('source/_templates')
@@ -15,38 +14,48 @@
1514
# so a file named "default.css" will overwrite the builtin "default.css".
1615
# html_static_path.append('source/_static')
1716

18-
if not on_rtd: # only import and set the theme if we're building docs locally
19-
import sphinx_rtd_theme
20-
html_theme = 'sphinx_rtd_theme'
21-
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
22-
2317
master_doc = 'index'
2418
# If extensions (or modules to document with autodoc) are in another directory,
2519
# add these directories to sys.path here. If the directory is relative to the
2620
# documentation root, use os.path.abspath to make it absolute, like shown here.
27-
root = path('../../..').abspath()
21+
root = Path('../../..').abspath()
2822
sys.path.insert(0, root)
2923
sys.path.append(root / "analytics_data_api/v0/views")
3024
sys.path.append('.')
3125

3226
# -- General configuration -----------------------------------------------------
3327

3428
# django configuration - careful here
35-
if on_rtd:
36-
os.environ['DJANGO_SETTINGS_MODULE'] = 'analyticsdataserver.settings.local'
37-
else:
38-
os.environ['DJANGO_SETTINGS_MODULE'] = 'analyticsdataserver.settings.local'
29+
os.environ['DJANGO_SETTINGS_MODULE'] = 'analyticsdataserver.settings.local'
30+
django.setup()
3931

4032
# Add any Sphinx extension module names here, as strings. They can be extensions
4133
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
4234
extensions = [
35+
'edx_theme',
4336
'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
44-
'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath',
37+
'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.imgmath',
4538
'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
4639

4740
# List of patterns, relative to source directory, that match files and
4841
# directories to ignore when looking for source files.
4942
exclude_patterns = ['build', 'links.rst']
5043

51-
project = 'Open edX Data Analytics API Version 0 Alpha'
52-
copyright = '2015, edX'
44+
project = 'Open edX Data Analytics API'
45+
copyright = '2021, edX'
46+
47+
# -- Options for HTML output ----------------------------------------------
48+
49+
# The theme to use for HTML and HTML Help pages. See the documentation for
50+
# a list of builtin themes.
51+
#
52+
html_theme = 'edx_theme'
53+
54+
# Theme options are theme-specific and customize the look and feel of a theme
55+
# further. For a list of options available for each theme, see the
56+
# documentation.
57+
#
58+
# html_theme_options = {}
59+
60+
# Add any paths that contain custom themes here, relative to this directory.
61+
html_theme_path = [edx_theme.get_html_theme_path()]

‎docs/api/source/courses.rst‎

Lines changed: 48 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
Course Information API
33
#######################
44

5-
.. contents:: Section Contents
5+
.. contents:: Section Contents
66
:local:
77
:depth: 1
8-
8+
99
.. _Get Weekly Course Activity:
1010

1111
***************************
@@ -16,12 +16,12 @@ Get Weekly Course Activity
1616

1717
**Example Response**
1818

19-
.. code-block:: json
19+
.. code-block::
2020
21-
HTTP 200 OK
22-
Vary: Accept
23-
Content-Type: text/html; charset=utf-8
24-
Allow: GET, HEAD, OPTIONS
21+
HTTP 200 OK
22+
Vary: Accept
23+
Content-Type: text/html; charset=utf-8
24+
Allow: GET, HEAD, OPTIONS
2525
2626
[
2727
{
@@ -45,12 +45,12 @@ Get Recent Course Activity
4545

4646
**Example Response**
4747

48-
.. code-block:: json
48+
.. code-block::
4949
50-
HTTP 200 OK
51-
Vary: Accept
52-
Content-Type: text/html; charset=utf-8
53-
Allow: GET, HEAD, OPTIONS
50+
HTTP 200 OK
51+
Vary: Accept
52+
Content-Type: text/html; charset=utf-8
53+
Allow: GET, HEAD, OPTIONS
5454
5555
{
5656
"interval_start": "2014-12-08T00:00:00Z",
@@ -70,12 +70,12 @@ Get the Course Enrollment
7070

7171
**Example Response**
7272

73-
.. code-block:: json
73+
.. code-block::
7474
75-
HTTP 200 OK
76-
Vary: Accept
77-
Content-Type: text/html; charset=utf-8
78-
Allow: GET, HEAD, OPTIONS
75+
HTTP 200 OK
76+
Vary: Accept
77+
Content-Type: text/html; charset=utf-8
78+
Allow: GET, HEAD, OPTIONS
7979
[
8080
{
8181
"course_id": "edX/DemoX/Demo_Course",
@@ -95,12 +95,12 @@ Get the Course Enrollment by Mode
9595

9696
**Example Response**
9797

98-
.. code-block:: json
98+
.. code-block::
9999
100-
HTTP 200 OK
101-
Vary: Accept
102-
Content-Type: text/html; charset=utf-8
103-
Allow: GET, HEAD, OPTIONS
100+
HTTP 200 OK
101+
Vary: Accept
102+
Content-Type: text/html; charset=utf-8
103+
Allow: GET, HEAD, OPTIONS
104104
105105
[
106106
{
@@ -125,12 +125,12 @@ Get the Course Enrollment by Birth Year
125125

126126
**Example Response**
127127

128-
.. code-block:: json
128+
.. code-block::
129129
130-
HTTP 200 OK
131-
Vary: Accept
132-
Content-Type: text/html; charset=utf-8
133-
Allow: GET, HEAD, OPTIONS
130+
HTTP 200 OK
131+
Vary: Accept
132+
Content-Type: text/html; charset=utf-8
133+
Allow: GET, HEAD, OPTIONS
134134
135135
[
136136
{
@@ -159,12 +159,12 @@ Get the Course Enrollment by Education Level
159159

160160
**Example Response**
161161

162-
.. code-block:: json
162+
.. code-block::
163163
164-
HTTP 200 OK
165-
Vary: Accept
166-
Content-Type: text/html; charset=utf-8
167-
Allow: GET, HEAD, OPTIONS
164+
HTTP 200 OK
165+
Vary: Accept
166+
Content-Type: text/html; charset=utf-8
167+
Allow: GET, HEAD, OPTIONS
168168
169169
[
170170
{
@@ -193,12 +193,12 @@ Get the Course Enrollment by Gender
193193

194194
**Example Response**
195195

196-
.. code-block:: json
196+
.. code-block::
197197
198-
HTTP 200 OK
199-
Vary: Accept
200-
Content-Type: text/html; charset=utf-8
201-
Allow: GET, HEAD, OPTIONS
198+
HTTP 200 OK
199+
Vary: Accept
200+
Content-Type: text/html; charset=utf-8
201+
Allow: GET, HEAD, OPTIONS
202202
203203
[
204204
{
@@ -224,12 +224,12 @@ See `ISO 3166 country codes`_ for more information.
224224

225225
**Example Response**
226226

227-
.. code-block:: json
227+
.. code-block::
228228
229-
HTTP 200 OK
230-
Vary: Accept
231-
Content-Type: text/html; charset=utf-8
232-
Allow: GET, HEAD, OPTIONS
229+
HTTP 200 OK
230+
Vary: Accept
231+
Content-Type: text/html; charset=utf-8
232+
Allow: GET, HEAD, OPTIONS
233233
234234
[
235235
{
@@ -266,12 +266,12 @@ Get the Course Video Data
266266

267267
**Example Response**
268268

269-
.. code-block:: json
269+
.. code-block::
270270
271-
HTTP 200 OK
272-
Vary: Accept
273-
Content-Type: text/html; charset=utf-8
274-
Allow: GET, HEAD, OPTIONS
271+
HTTP 200 OK
272+
Vary: Accept
273+
Content-Type: text/html; charset=utf-8
274+
Allow: GET, HEAD, OPTIONS
275275
276276
[
277277
{
@@ -295,7 +295,7 @@ Get the Course Video Data
295295
"users_at_start": 1044,
296296
"users_at_end": 0,
297297
"created": "2015-04-15T214158"
298-
},
298+
},
299299
]
300300
301301
.. include:: links.rst

‎docs/api/source/problems.rst‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,26 @@
22
Problem Information API
33
########################
44

5-
.. contents:: Section Contents
5+
.. contents:: Section Contents
66
:local:
77
:depth: 1
8-
8+
99
.. _Get the Grade Distribution for a Course:
1010

1111
***************************************
1212
Get the Grade Distribution for a Course
1313
***************************************
1414

15-
.. autoclass:: analytics_data_api.v0.views.problems.GradeDistributionView
15+
.. autoclass:: analytics_data_api.v0.views.problems.GradeDistributionView
1616

1717
**Example Response**
1818

19-
.. code-block:: json
19+
.. code-block::
2020
21-
HTTP 200 OK
22-
Vary: Accept
23-
Content-Type: text/html; charset=utf-8
24-
Allow: GET, HEAD, OPTIONS
21+
HTTP 200 OK
22+
Vary: Accept
23+
Content-Type: text/html; charset=utf-8
24+
Allow: GET, HEAD, OPTIONS
2525
2626
[
2727
{
@@ -52,12 +52,12 @@ Get the Answer Distribution for a Problem
5252

5353
**Example Response**
5454

55-
.. code-block:: json
55+
.. code-block::
5656
57-
HTTP 200 OK
58-
Vary: Accept
59-
Content-Type: text/html; charset=utf-8
60-
Allow: GET, HEAD, OPTIONS
57+
HTTP 200 OK
58+
Vary: Accept
59+
Content-Type: text/html; charset=utf-8
60+
Allow: GET, HEAD, OPTIONS
6161
6262
[
6363
{
@@ -72,7 +72,7 @@ Get the Answer Distribution for a Problem
7272
"answer_value_text": "Russia",
7373
"answer_value_numeric": null,
7474
"problem_display_name": "Multiple Choice Problem",
75-
"question_text": "Which of the following countries has the largest
75+
"question_text": "Which of the following countries has the largest
7676
population?",
7777
"variant": null,
7878
"created": "2014-12-05T225026"
@@ -89,7 +89,7 @@ Get the Answer Distribution for a Problem
8989
"answer_value_text": "Indonesia",
9090
"answer_value_numeric": null,
9191
"problem_display_name": "Multiple Choice Problem",
92-
"question_text": "Which of the following countries has the largest
92+
"question_text": "Which of the following countries has the largest
9393
population?",
9494
"variant": null,
9595
"created": "2014-12-05T225026"
@@ -106,12 +106,12 @@ Get the View Count for a Subsection
106106

107107
**Example Response**
108108

109-
.. code-block:: json
109+
.. code-block::
110110
111-
HTTP 200 OK
112-
Vary: Accept
113-
Content-Type: text/html; charset=utf-8
114-
Allow: GET, HEAD, OPTIONS
111+
HTTP 200 OK
112+
Vary: Accept
113+
Content-Type: text/html; charset=utf-8
114+
Allow: GET, HEAD, OPTIONS
115115
116116
[
117117
{

0 commit comments

Comments
 (0)