From 766122be7fad43d15da069382731aaee6e636a22 Mon Sep 17 00:00:00 2001 From: rsiddharth Date: Thu, 12 May 2016 21:36:21 +0000 Subject: update README.rst - all documentation is being moved to docs/ - installation documentation is at docs/install/index.rst --- README.rst | 319 ++++--------------------------------------------- docs/index.rst | 23 +--- docs/install/index.rst | 39 ++++++ 3 files changed, 64 insertions(+), 317 deletions(-) create mode 100644 docs/install/index.rst diff --git a/README.rst b/README.rst index 4873719..0dcb211 100644 --- a/README.rst +++ b/README.rst @@ -1,313 +1,34 @@ -LibrePlanet schedule generator -============================== +lpschedule-generator +==================== -Installation ------------- +Python package that enables the FSF_ to write the LibrePlanet_ +schedule in Markdown_. -On a Debian based distribution, do:: +To get started see "Installation_". - # aptitude install virtualenv python-setuptools +.. _Installation: https://pythonhosted.org/lpschedule-generator/install +.. _FSF: https://fsf.org +.. _LibrePlanet: https://libreplanet.org/conference +.. _Markdown: https://daringfireball.net/projects/markdown -Install globally -~~~~~~~~~~~~~~~~ +canonical repo +-------------- :: - $ sudo pip install lpschedule-generator - - -Install locally using virtualenv (Recommended) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Make a separate ``lpschedule-generator`` directory and initialize the -virtual environment in it:: - - $ mkdir lpschedule-generator - $ cd lpschedule-generator - - $ virtualenv . - $ source bin/activate - -Install ``lpschedule-generator`` inside this directory using ``pip``:: - - $ pip install lpschedule-generator - -Activating virtual environment -`````````````````````````````` - -Always activate the virtual environment before using the ``lps_gen`` -command:: - - $ cd path/to/lpschedule-generator - $ source bin/activate - - -LP schedule ------------ - -LP schedule usage -~~~~~~~~~~~~~~~~~ -:: - - $ lps_gen -s path/to/lp-sch.jinja2 path/to/lp-sch.md > path/to/program-schedule.html - -or:: - - $ lps_gen --schedule path/to/lp-schedule.jinja2 path/to/lp-sch.md > path/to/program-schedule.html - - -LP schedule markdown structure -`````````````````````````````` - -Overall structure:: - - ## Day 1 - - ### Timeslot 1 - - #### Session 1 - - #### Session 2 - - ... - - ### Timeslot 2 - - #### Session 1 - - #### Session 2 - - ... - - ## Day 2 - - ### Timeslot 1 - - #### Session 1 - - #### Session 2 - - ... - -Level two heading (``##``) format:: - - ## Saturday, March 19 - - ... - - ## Sunday, March 20 - -Level three heading (``###``) format:: - - ### 09:00 - 09:45: Registration and Breakfast - - ### 09:45 - 10:45: Opening Keynote - - ... - - ### 10:55 - 11:40: Session Block 1A - -Session structure:: - - #### Fork and ignore: fighting a GPL violation by coding instead - - [Bradley Kuhn][kuhn], [Karen Sandler][sandler] - - Room 32-155 - - Typically, GPL enforcement activity involves copyright infringement - actions which compel license violators to correct errors in their - GPL compliance, defending the policy goals of the GPL: the rights of - developers and users to copy, share, modify and redistribute. - - While traditional enforcement is often undeniably necessary for - embedded electronics products, novel approaches to GPL violations - are often possible and even superior for more traditional software - distributions. - - Recently, [Software Freedom Conservancy][sfc] engaged in an - enforcement action whereby, rather than fight the violator in court, - we instead provided resources and assistance to a vetted - GPL-compliant fork of a violating codebase. - - This talk discusses which scenarios make this remedy optimal and the - lessons learned. The talk includes some licensing and technical - content about vetting the licensing information of codebases. - - [kuhn]: https://libreplanet.org/YEAR/path/to/speakers.html#kuhn - [sandler]: https://libreplanet.org/YEAR/path/to/speakers.html#sandler - [sfc]: https://sfconservancy.org/ - -Sample: https://notabug.org/rsd/lpschedule-generator/raw/dev/tests/files/lp-sch.md - - -Auto-linking speaker names -++++++++++++++++++++++++++ - -Speakers in the schedule MD can be auto-linked to speakers' page by -marking them up like this ``[John Hacker]()`` - -The script converts: - -- ``[John Hacker]()`` to ``John - Hacker`` if John Hacker's bio is available in the speakers' page. - -- ``[John Hacker]()`` to ``John Hacker`` if John Hacker's bio is not - available in the speakers' page. In this case, the script also appends - ``John Hacker`` name in the ``speakers.noids`` file. - - The ``speakers.noids`` file contains a list of speakers who were - auto-linked in the schedule MD but who's bio is not (yet) available - in the speakers' page. - -For auto-linking speakers, the script uses the ``speakers.ids`` file; -this file is written to the disk after generating the the speakers' -page from MD. Generate the speakers' page before generating the -schedule page for auto-linking to work. - -Sample: https://notabug.org/rsd/lpschedule-generator/raw/dev/tests/files/lp-sessions-autolink.md - -Special cases -+++++++++++++ - -Speaker TBA -........... - -When the speaker information for a session is not yet available put -``SpeakerTBA`` as the placeholder in the line that usually contains -the speaker information; the rendered HTML will not have speaker -information for sessions that have ``SpeakerTBA``. - -Room TBA -........ - -When a room for a session is not yet available put ``RoomTBA`` as the -placeholder in the line that usually contains the room number; the -rendered HTML will not have the room number for sessions that have -``RoomTBA``. - -Description TBA -............... - -When the description for session is not yet available put ``DescTBA`` -as the placeholder; the rendered HTML will not have the description -for sessions that have ``DescTBA``. - -Sample: https://notabug.org/rsd/lpschedule-generator/raw/dev/tests/files/lp-sch-tba.md - -Sessions only schedule -...................... - -It is possible to have a sessions only schedule. To do this, at the -beginning of the markdown document: - -- Add a level two heading (``##``) with one or more whitespaces. -- Add a level three heading (``###``) with one or more whitespaces. - -Sessions only sample: https://notabug.org/rsd/lpschedule-generator/raw/dev/tests/files/lp-sch-sessions-only.md - - -LP schedule iCal export -~~~~~~~~~~~~~~~~~~~~~~~ - -The ``--ical`` switch enables iCal export while generating LP -schedule:: - - $ lps_gen -s --ical 2016 path/to/lp-schedule.jinja2 path/to/lp-schedule.md > path/to/program-schedule.html - -The year of the conference must be given as an argument to the -``--ical`` switch. - - -LP speakers ------------ - -LP speakers usage -~~~~~~~~~~~~~~~~~ -:: - - $ lps_gen -sp path/to/lp-speakers.jinja2 path/to/lp-speakers.md > path/to/speakers-content.html - -or:: - - $ lps_gen --speakers path/to/lp-speakers.jinja2 path/to/lp-speakers.md > path/to/speakers-content.html - -LP speakers markdown structure -`````````````````````````````` - -:: - - # Keynote speaker name 1 - - ![Keynote speaker name 1 - Photo](//fsf.org/images/ks1.jpg) - - Lorem ipsum dolor sit amet keynote speaker 1 bio; can contain - inline HTML. - - # Keynote speaker name 2 - - ![Keynote speaker name 2 - Photo](//fsf.org/images/ks2.jpg) - - Lorem ipsum dolor sit amet keynote speaker 2 bio; can contain - inline HTML. - - ... - - ## Speaker name 1 - - ![Speaker name 1 - Photo](//fsf.org/images/s1.jpg) - - Lorem ipsum dolor sit amet speaker 1 bio; can contain inline HTML. - - ## Speaker name 2 - - ![Speaker name 2 - Photo](//fsf.org/images/s2.jpg) - - Lorem ipsum dolor sit amet speaker 2 bio; can contain inline HTML. - - ... - - -Everything except the speaker name is optional. - -Sample: https://notabug.org/rsd/lpschedule-generator/raw/dev/tests/files/lp-speakers.md - -Speaker's ID generation -+++++++++++++++++++++++ - -The last name of the speaker is automatically made the ID; if a -speaker' name is "John Hacker", the ID for this speaker will be -``hacker``. - -- If two or more speakers have the same last name, then, the first - speaker will have their last name as their ID and from the second to - the n^th speaker will have their full name as their ID; if "Bill - Hacker" and "Jill Hacker" are two speakers, "Bill" will get - ``hacker`` as his ID and "Jill" will get ``jill_hacker`` as her ID. + $ git clone https://notabug.org/rsd/lpschedule-generator.git -- The IDs are transliterated to ASCII; if a speaker' name is "John - HÖcker", the ID for this speaker will be ``hacker``. -General +license ------- -Commenting -~~~~~~~~~~ - -The markdown files can have comments in the `following three formats`__:: - - [comment]: <> (This is one type of comment.) - [//]: <> (This is another type of comment.) - [//]: # (This is the third type of comment.) - -The comments won't make it to the generated HTML. +lpschedule-generator is licensed under the `GNU Generaly Public +license version 3 or later`__. -.. _md_comments: https://stackoverflow.com/questions/4823468/comments-in-markdown -__ md_comments_ +.. _gplv3: https://www.gnu.org/licenses/gpl-3.0-standalone.html +__ gplv3_ -Source ------- +help +---- -:: - - $ git clone https://notabug.org/rsd/lpschedule-generator.git +Contact rsiddharth . diff --git a/docs/index.rst b/docs/index.rst index c95a198..c3203a8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,22 +1,9 @@ -.. lpschedule-generator documentation master file, created by - sphinx-quickstart on Wed May 11 19:54:18 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. highlight:: bash -Welcome to lpschedule-generator's documentation! -================================================ - -Contents: +.. include:: ../README.rst .. toctree:: - :maxdepth: 2 - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + :hidden: + Home + install/index diff --git a/docs/install/index.rst b/docs/install/index.rst new file mode 100644 index 0000000..7a4fe0b --- /dev/null +++ b/docs/install/index.rst @@ -0,0 +1,39 @@ +Installation +------------ + +On a Debian based distribution, do:: + + # aptitude install virtualenv python-setuptools + +Install globally +~~~~~~~~~~~~~~~~ + +:: + + $ sudo pip install lpschedule-generator + + +Install locally using virtualenv (Recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Make a separate ``lpschedule-generator`` directory and initialize the +virtual environment in it:: + + $ mkdir lpschedule-generator + $ cd lpschedule-generator + + $ virtualenv . + $ source bin/activate + +Install ``lpschedule-generator`` inside this directory using ``pip``:: + + $ pip install lpschedule-generator + +Activating virtual environment +`````````````````````````````` + +Always activate the virtual environment before using the ``lps_gen`` +command:: + + $ cd path/to/lpschedule-generator + $ source bin/activate -- cgit v1.2.3