Update: docs on creating a custom book.

Author: bnmnetp

README.rst

@@ -5,10 +5,10 @@ Runestone Academy is an open source project and *our mission is to equip the nat
 
 
 * Using a Runestone Academy for my class - `Instructor guide <https://guide.runestone.academy>`_
-* Running a server for my own class?
-* Running a server for my school or larger group?
+* Running a server for my own class? - coming soon
+* Running a server for my school or larger group? - coming soon
 * I want to author a book - `Author Guide <https://pretextbook.org/doc/guide/html/guide-toc.html>`_
-* I want to customize a book for my class
+* I want to customize a book for my class - `Customizing a Textbook <https://runestone-monorepo.readthedocs.io/en/latest/custom_book.html>`_
 * I want to contribute to the Runestone Academy software - `Contributing Guide <https://runestone-monorepo.readthedocs.io/en/latest/contributing.html>`_
 * What is Runestone Academy? - `About Runestone <https://landing.runestone.academy>`_
 

docs/source/custom_book.rst

@@ -0,0 +1,33 @@
+Customizing a Textbook on Runestone Academy
+===========================================
+
+This is a guide for customizing a textbook on Runestone Academy.  It is intended for instructors who are using Runestone Academy to host their course materials, but who want to make some changes to the textbook.  For example, you might want to add a new chapter, or add some new exercises to an existing chapter.
+
+First, I'm going to try to discourage you from going any further.   Someday we hope to make customizing Runestone books very easy.  Today it requires facility with github and writing in PreTeXt and maybe a few other skills.  The most common reasons I hear from teachers for wanting to customize there books are:
+
+1. I want to hide some materials from my students.  **Why??**  Why would you prevent your students from reading ahead or learning extra materials?  If you have a curious and motivated student why hold them back?  They can always find the material in the "open course" that uses the same book anyway.
+2. I want to rearrange the order of some chapters.  This is much easier said than done.  Any textbook author will tell you that the order of the chapters is a very carefully thought out process.  With each chapter building on the chapters before it.  Simply moving chapters around without doing significant rewriting is going to lead to a very frustrating experience for your students.
+3. I want to add additional exercises.  This is a great thing to do, but is already supported through our web interface.  See the `Instructor guide <https://guide.runestone.academy>` for more information.
+
+The last thing I will say to discourage you is that if you do customize your book, you will need to maintain it.  If you are using a book that is maintained by someone else, then you can benefit from their work.  If you customize your book, then you will need to keep up with any changes that are made to the original book.  This is not a trivial task.   It also takes additional resources on Runestone academy for every additional book.  Hosting a book that is only being used by one class is not a great use of our resources, and it takes up some time from our staff (me) to help you get your book set up.
+
+If you are still reading, then I will assume that you have a good reason for wanting to customize your book.  I will also assume that you have some familiarity with github and PreTeXt.  If you don't, then you should probably stop here and go learn about those things first.
+
+There are some good reasons to want to customize a book.  
+
+1. I want to provide more culturally relevant examples.  This is a great reason to customize a book.  If you want to add some examples that are more relevant to your students, then you should do that.  You can even contribute those changes back to the original book so that others can benefit from your work.
+2. I want to add an additional chapter that covers new material not covered in the book.  This is also a great reason to customize a book.  You can add a new chapter, and then add links to that chapter from the existing chapters.  You can even contribute that chapter back to the original book so that others can benefit from your work.
+3. I have a better way of explaining something than the original author.  Great, you can change the text to make it better.  But before you go to all the work of a custom book it might be a good idea to engage the original author in a discussion about your ideas.  They might be able to incorporate your ideas into the original book, and then everyone benefits.  Authors who write Open Source textbooks are usually very open to suggestions and improvements.
+
+
+Getting Started
+===============
+
+1. Create a fork of the book you want to customize.  Most of the books on Runestone Academy have Forks from our RunestoneInteractive organization.  For some others the repositories are easy to find if you look at the book, or just do a github search
+2. Create an issue on `Github, here <https://github.com/RunestoneInteractive/rs>`_ to let me know you are working on a custom book.  Please include the name of the book and the document-id. This will allow me to be sure that the document-id is not already in use.
+4. Clone your fork to your local machine.  You will need to have git installed on your machine. 
+5. Make your changes.
+6. Commit your changes and push them back to github.
+7. Make sure you consult the section in the `PreTeXt Guide <https://pretextbook.org/doc/guide/html/sec-publishing-to-runestone-academy.html>`_ on publishing to Runestone Academy.
+8. Update the issue to let me know you are ready to publish.  I will then add your book to Runestone Academy, and set you up as an author so that you can publish changes directly to Runestone Academy.
+

docs/source/developing.rst

@@ -213,6 +213,7 @@ If you install postgresql locally you will need to do  a few things to get it re
 5. Configure the pg_hba.conf file to allow access from the docker network.  This is done by adding a line like this to the file ``host all all 0.0.0.0/0 md5``.  You can find this file by running ``pg_config --sysconfdir``.  On my mac it is ``/usr/local/var/postgres``. On many linux varieties it is something like ``/etc/postgresql/14/main/`` See above.   You will need to restart postgresql for this to take effect.
 6. Restart Postgresql.  On my mac this is done by running ``brew services restart postgresql``.  On linux it is probably ``sudo service postgresql restart``
 7. After you restart try the following command ``psql -h localhost -U runestone runestone_dev``  You should be prompted for a password.  Enter the password you created for the runestone user.  You should then be at a psql prompt.  You can exit by typing ``\q``  If you cannot connect then you have done something wrong.  You can ask for help in the ``developer-forum`` channel on the Runestone discord server.
+8. Use the `rsmanage initdb` command to create the database schemas and populate some initial data for common courses, as well as create `testuser1` with password "xxx" yes three x's super secure.  You can change this password later.  You can also create your own user with the ``rsmanage adduser`` command.  You can also use the ``rsmanage resetpw`` command to change the password for testuser1.
 
 Install Postgresql with Docker
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -222,7 +223,7 @@ If you do not want to install postgresql on your host, or maybe you are just loo
 1. Before you build the rest of the services run the command ``docker compose -f docker-compose.yml -f author.compose.yml -f db.compose.yml up -d db``  This will start just the database service in the set of composed services.   It will also use the default settings for ``POSTGRES_PASSWORD`` (runestone), ``POSTGRES_USER`` (runestone), and ``POSTGRES_DBNAME`` (runestone_dev).  You should change these if you are running a production server, but if you are just getting set up for development for the first time just leave them alone.
 2. Once the postgresql service has installed itself and started up you can initialize your database using the ``rsmanage`` command.  This assumes that you have already followed the instructions for installing poetry and the plugins.  You can run ``poetry install --with=dev`` from the top level directory to get a working virtual environment with the ``rsmanage`` command installed.  Run ``poetry shell`` to enable the newly created virtual environment.
 3. You will also need to have the minimal set of environment variables set up.  See the section below.  If you want to use the defaults you can set ``SERVER_CONFIG`` to ``development`` and ``DEV_DBURL`` to ``postgresql://runestone:runestone@localhost:2345/runestone_dev``  rsmanage will tell you if you are missing any environment variables.
-4. Run `` rsmanage initdb`` This will create the database and initialize it with the tables and data that you need.  Note that this sets the DEV_DBURL environment variable for the ``rsmanage`` command.  If you already have that set then you can omit that part of the command.
+4. Run ``docker compose run rsmanage rsmanage initdb`` This will build the image in docker for the rsmanage command and then run it to create the database and initialize it with the tables and data that you need.  You can use ``docker compose run rsmanage rsmanage ...`` to run any of the rsmanage commands in the composed app.   If you prefer you can install ``rsmanage`` on the host and run it there, but you will need to be mindful of your environment variables related to the database.
 
 At this point your database is ready