Skip to content

Commit 445c73e

Browse files
author
Philip Hansen
committed
README instructions
The readme has been written with installation and usage instructions.
1 parent de8d314 commit 445c73e

File tree

2 files changed

+200
-2
lines changed

2 files changed

+200
-2
lines changed

‎README.rst‎

Lines changed: 196 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,196 @@
1-
Hello World
1+
LecToCal
2+
========
3+
4+
Lectocal is a python utility for synchronizing schedules from Lectio_ into
5+
`Google Calendar`_. It allows students and teachers of any institution using
6+
lectio, to see their schedules in a calendar platform they may already
7+
be using.
8+
9+
Ultimately the purpose is to make it easier for members of
10+
institutions using lectio to stay on top of their schedules, by allowing
11+
the use of features such as email notifications, and push notifications
12+
on Android and iOS devices, together with the lectio schedule.
13+
14+
.. _Lectio: http://www.lectio.dk/
15+
.. _`Google Calendar`: https://calendar.google.com/
16+
17+
Installation
18+
------------
19+
20+
The source files for lectocal can be downloaded directly from the
21+
`GitHub Repository`_, if you wish to work with the source code, feel free
22+
to download it there.
23+
24+
The recommended installation method for normal use is however through pip,
25+
as this will take care of installing any dependencies necessary,
26+
and install the modules directly used by the end user as executables.
27+
28+
To install using pip run:
29+
30+
::
31+
32+
pip install lectocal
33+
34+
For more details on using pip, see `Installing Packages`_ by the
35+
Python Packaging Authority.
36+
37+
.. _`GitHub Repository`: https://github.com/Hanse00/LecToCal
38+
.. _`Installing Packages`: http://python-packaging-user-guide.readthedocs.org/en/latest/installing/
39+
40+
Usage
41+
-----
42+
43+
Dependencies
44+
............
45+
46+
lectocal has a number of dependencies, if installed through pip these will
47+
be handled automatically, otherwise they must manually be installed.
48+
49+
As with lectocal, it is recommended these are installed through pip.
50+
51+
Lectocal has the following dependencies:
52+
53+
- google-api-python-client
54+
- requests
55+
- lxml
56+
- pytz
57+
- python-dateutil
58+
59+
They can be installed through pip with:
60+
61+
::
62+
63+
pip install google-api-python-client requests lxml pytz python-dateutil
64+
65+
Invoking the modules
66+
....................
67+
68+
Once you have lectocal installed (preferably through pip), there's a number of
69+
ways to invoke the two modules you'll primarily be using:
70+
71+
- run.py
72+
- gauth.py
73+
74+
The modules can either be executed as python files:
75+
76+
::
77+
78+
python run.py
79+
python gauth.py
80+
81+
They can also be fed to python as modules:
82+
83+
::
84+
85+
python -m run
86+
python -m gauth
87+
88+
Finally, if the package was installed by setuptools (This is done automatically
89+
by pip) two executable scrips will be generated:
90+
91+
::
92+
93+
lectocal.run
94+
lectocal.gauth
95+
96+
(Native executable .exe files should be generated on Windows systems)
97+
98+
Parameters
99+
..........
100+
101+
A number of parameters are supported when running the run and gauth modules.
102+
The current list can always be seen by running the modules with the ``-h`` flag.
103+
As such:
104+
105+
::
106+
107+
python run.py -h
108+
python -m run -h
109+
lectocal.run -h
110+
111+
How to use
112+
..........
113+
114+
Using lectocal consists of two distinct steps, of which the first should
115+
only be required once, and the second can be repeated to update the calendar.
116+
117+
Step 1
118+
::::::
119+
120+
Generating the user OAuth credentials.
121+
122+
Before it's possible to start reading and writing data to the user's Google
123+
Calendar, we must obtain OAuth credentials authorizing the package to interact
124+
with it.
125+
126+
This is done by running the ``gauth`` module, which will use the client secret
127+
file provided with the package, together with the user authenticating through
128+
a web browser, to generate a credentials file.
129+
130+
See ``gauth -h`` for a list of possible parameters, however the default values
131+
should be acceptable in most usecases.
132+
133+
After the credentials file has been obtained, it can be used to sync the schedules.
134+
135+
Step 2
136+
::::::
137+
138+
Synchronizing Lectio schedule to Google Calendar.
139+
140+
With the credentials file, we are authorized to interact with the user's
141+
Google Calendar. We can therefore now run the ``run`` module, to scrape the
142+
Lectio schedule, and write it into Google Calendar.
143+
144+
If you're running the ``run`` module for the first time for a given user,
145+
the full schedule will simply be copied over. On every subsequent invocation
146+
of the module, it will determine which, if any, lessons have changed since the
147+
last schedule sync, and update those with the new data.
148+
149+
The ``run`` module takes 3 positional arguments, which are required to run
150+
the module. Other arguments can be seen with ``run -h``, however the defaults
151+
for there should suffice in most cases.
152+
153+
The positional arguments are:
154+
155+
::
156+
157+
run school_id user_type user_id
158+
159+
- school_id
160+
This is the id number of the school, at which the user is a member,
161+
in Lectio's system.
162+
163+
It can be found by browsing to your school's front page (eg.
164+
http://www.lectio.dk/lectio/523/default.aspx), the school id is the number
165+
in the page URL, in my case 523.
166+
167+
- user_type
168+
The user type can take one of two values, depending on if the user
169+
you are trying to sync schedules for, is registered as a teacher or a
170+
student in Lectio.
171+
172+
The possible values are: ``student`` and ``teacher``.
173+
174+
- user_id
175+
This is the id number of a user within a given school, in lectio these
176+
are known as elevid or laererid depending on which type the user has.
177+
Both of these id types are used as user_id in lectocal.
178+
179+
To find the id of a user, open their schedule page (eg.
180+
http://www.lectio.dk/lectio/523/SkemaNy.aspx?type=elev&elevid=2486079338)
181+
the user id number, is the number behind elevid= or laererid= depending
182+
on the user type, in this case 2486079338.
183+
184+
Invoking the script will therefor look like this:
185+
186+
::
187+
188+
run 523 student 2486079338
189+
190+
License
191+
-------
192+
LecToCal is licensed under the Apache 2.0 license, see LICENSE_ or
193+
apache.org_ for details.
194+
195+
.. _LICENSE: LICENSE
196+
.. _apache.org: http://www.apache.org/licenses/LICENSE-2.0

‎setup.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,10 @@
2929

3030
# Environment Type
3131
"Environment :: No Input/Output (Daemon)",
32-
"Environment :: Web Environment"
32+
"Environment :: Web Environment",
33+
34+
# License
35+
"License :: OSI Approved :: Apache Software License"
3336
],
3437
keywords="lectio google calendar sync utility",
3538
packages=find_packages(),

0 commit comments

Comments
 (0)