Package: iacs-cli
iacs-cliWhat isiacs-cli?iacs-cli is a course website generator powered byPelican, a Python static site
generator, which will enable a course instructor to quickly convert course
content into a web content for students and the public. Some of the challenges
faced by IACS course instructor include:Creating course materials often in Jupyter notebook, R markdown document, or
Powerpoint slides. Unfortunately, course instructors are expected to upload
these materials on to a website that must be maintained separately from course
content. That means instructors must be versed in HTML, CSS, and sometimes
JavaScript as well as website deployment. Ideally, course instructor should
focus 100% of his or her effort in course content development and delegate
website development to someone else.Every IACS course instructor organizes the course project in his or her
project organizational structure. This makes navigating course materials
challenging for a new course instructor who takes over the curriculum.Moreover, because of the lack of convention in how the course content is
presented online, students also face difficulty of quickly finding materials
on topic of their curiosity. Ideally, IACS course website should follow a
consistent “look-and-feel,” and searching for learning contents should be
intuitive and easy.Course instructor should be able to quickly leverage existing content from
the previous iteration of the course instead of starting the course project
from scratch. Moreover, if course materials are organized following the same
convention, it will be easier for course instructors to pull materials from
other courses and integrate them into another course. For instance, if CS109
Data Science must borrow concepts from AM207 Monte Carlo Methods, CS109
instructor can copy the material - provided that CS109 course instructor has
been proper credited - and present the material with small modifications and
no concern for HTML and CSS.iacs-clialleviates these problems by enforcing course organization
conventions and automatic generation of static HTML and CSS files. In
addition to the static website generation, additional features ofiacs-cliinclude:Automatic topic index generation – course content can be organized around
topics if a course designer provides “tags” information in the metadata of the content.Search course content by topic – Like the topic index, if a course designer
provides “tags” information, the website can be searched by topic of interest.Customizable Web Design with minimal knowledge of HTML and CSS.Without touching HTML or CSS, course designer can customize color of the
website albeit maintaining consistent “feel” for IACS course.Installation/Setupiacs-cliis a PyPi package. In order to install through PyPi, use pip
command in the command console:$ pip install iacs-cliThis command will installiacs-clialong with its dependencies:ClickPelicanMarkdownGitPythonWorkflowCreate a new project - Take the command console to the directory where you want to place your course content, and create the course using the following command:$ iacs create 'course_name'The standard convention we would like the instructors to use is YYYY-Course-Name.For example, for Fall 2017 CS109A, we would name the course project as 2017-CS109A.Create the Home Page - The markdown document that converts to the home page
of the website is pre-populated when you create the project directory. It is
located in content/index.mdYou must provide Title of the course and Date when the document was created.Do not modify save_as: index.html, unless you do not want to use this document as the home page of your course websiteCreate other pages such as Syllabus, Policies, Resources, etc.Every page that is not a course content such as the syllabus or resources page,
create markdown document (with the metadata of Title, Slug, and Date) inside
the directorycontent/pages/.Here, Slug refers to the url to the webpage to be generated from the
document. For instance, Slug: syllabus will generate a url pointing to the
syllabus page: http://<course_website>/pages/syllabus.htmlCreate the Schedule pageiacs-clienables course designers to create a table of course schedule using
csv file. In the publication process, the command line tool will automatically
convert the csv table into a markdown table, which in turn will be converted
to a HTML table.When course designer creates a new project, schedule.csv file will be
automatically created insidecontent/pages/directory. Use Excel or similar
spreadsheet software to edit the schedule.csv file as shown below:Please note that any cell content that matches a title of markdown document,
then the created markdown will automatically link the markdown document to the
corresponding document. This auto-generated markdown table will then be
converted to HTML table with clickable links to the content of the course:Edit Content of the courseThere are two ways to create and edit contents of the course. One can create
a page using markdown or Ipython notebook.Suggested directory structure:ProjectDirectory
	content/
	labs/
lectures/
pages/
sections/
index.md
docs/
	plugins/
	ipynb/
	tipue_search/
	themes/
	static/
	templates/
	config.py
	README.mdIncluding Metadata
In order to convert course content written in markdown or Ipython notebook,
one must provide the following metadata information at the top of the document:TitleCategorySlugAuthorDateTags – Optional, but highly encouraged for topic indexing and searchIn markdown document, this may look like the example below:For metadata for IPython Notebook, you must create a metadata file with the
same name but with a prefix of “-meta”. For example (see below),
forlecture1213_notebook.ipynb, createlecture1213_notebook.ipynb-metaand provide metadata information at the top of the document.Linking documents within a projectIn order to create internal links between documents in a course, use markdown syntax for creating a link with {filename} prefix:(< description >)[{ filename }< path_to_file >]See example below:Including static files such as *.jpg, *.pdf, and *.pngFor links to static files such as PDF or embedding JPEG or PNG images
in markdown document, use {attach} prefix:(< description >)[{ attach }< path_to_file >]After creating contents for the website, course designer must generate
HTML and CSS documents using the following command inside the root directory
of the project:$ iacs publishThis command will populate the doc/ directory with static HTML and CSS files
for the website. To preview the website, use the following command inside
the root directory:$ iacs launchThis command will launch a Python localhost server with port number 8000. Open
up a browser and visithttp://localhost:8000/.Turning on GitHub PagesCommit and upload the git repo to Github.com. In settings page, enable GitHub
Pages and selectmaster branch /docsfolder as its source:Command ReferenceCreate a new project$ iacs create 'course_name'Publish the content$ iacs publishLaunch a localhost web server$ iacs launchCopy existing course projects$ iacs copy 'existing_course_dir' 'course_name'