Autolab Documentation Improvement (#1351)

* Modify mkdocs theme (#1289)

* Request for institution name in the bug template (#1285)

* Modify mkdocs material theme to have tabs and use autolab red

Co-authored-by: Victor Huang <[email protected]>

* Unify installation section in documentation (#1290)

* Setup new page for installation unification

* Split up ubuntu and osx installation pages

* Modify installation docs structure

* Change getting started to link to new installation page

* Separate out commands into its own block

* Change backtick code blocks to identation + colon style

* Move Tango installation instructions to installation tab

* Separate Tango deployment methods in docs

* Improve wording on TLS/SSL, and link to Tango installation section after completing manual Autolab setup

* Add minor change from SSL to TLS/SSL

Co-authored-by: xtrkil <[email protected]>

* Overview And Getting Started Sections for Documentation (#1299)

* Setup new page for installation unification

* Split up ubuntu and osx installation pages

* Modify installation docs structure

* Change getting started to link to new installation page

* Separate out commands into its own block

* Change backtick code blocks to identation + colon style

* Move Tango installation instructions to installation tab

* Separate Tango deployment methods in docs

* Improve wording on TLS/SSL, and link to Tango installation section after completing manual Autolab setup

* Add minor change from SSL to TLS/SSL

* Separated overview from getting started; restructured index a little bit.

* Restructure done; about to add in details for overview/introduction

* Added picture for Autolab system.

* Done with the initial draft for overview nad getting-started

Co-authored-by: Fan Pu <[email protected]>
Co-authored-by: xtrkil <[email protected]>

* Add information on creating root user to docs (#1304)

* move initialize_user.sh from docker/ to bin/

* Update ubuntu and osx installation docs on creating initial root user step

* Add init-user script

* Creates and Organizes Reference Section (#1302)

* Create new reference section

* Add reference overview

* Move vmms setup instructions from vmms api to tango overview

* Updates wording

* Updates wording on reference

* Small fixes and rollback from rollback (#1325)

* Fixed installation wrong link; did some reorganization on the part of Tango VMMS.

* Replaced VMMS setup instruction.

* Improve the overview section of the new documentation (#1340)

* Improve Overview.

* Adjust wording based on feedback.

* Move CLI sections into Getting Started (#1341)

* Make Reference section more catered to developers

* Remove tango.md

* Documentation FAQ Refinement (#1348)

* Reworded FAQ to Troubleshooting. Added pointers to troubleshooting sections.

* Fixed wording.

* Ensure all links are valid (#1349)

* Ensure all links are valid and outgoing links open in new tab

* Change outgoing link in tango.md to open in new tab

* Metrics docs refactoring with finalized wording (#1350)

* updating docs with finalized wording

* Documentation FAQ Refinement (#1348)

* Reworded FAQ to Troubleshooting. Added pointers to troubleshooting sections.

* Fixed wording.

* Ensure all links are valid (#1349)

* Ensure all links are valid and outgoing links open in new tab

* Change outgoing link in tango.md to open in new tab

* updating docs with finalized wording

* fixing page linking

Co-authored-by: xinyis991105 <[email protected]>
Co-authored-by: ashleyzhang <[email protected]>

* Add instructions on how to setup mailing on Autolab (#1336)

* Add smtp settings in production.rb and documentation

* Add instruction updates for development

* Added description of where config files are at

* fix syntax in mkdocs

Co-authored-by: ashleyzhang <[email protected]>
Co-authored-by: Victor Huang <[email protected]>
Co-authored-by: Fan Pu <[email protected]>
Co-authored-by: Fan Pu <[email protected]>
Co-authored-by: amartinez116 <[email protected]>

Author: 5 people

docker/initialize_user.sh renamed to bin/initialize_user.sh

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# This is the legacy One-Click install script
+# It probably doesn't work anymore, but is left here as reference
+
 #####################################
 ## Initialization & Helper Functions
 #####################################

bin/setup.sh

@@ -39,10 +39,7 @@ Autolab3::Application.configure do
     config.force_ssl = true
     config.middleware.use Rack::SslEnforcer, :except => [ /log_submit/, /local_submit/ ]
   end
-    
-    
-
-
+  
   # See everything in the log (default is :info)
   config.log_level = :info
 
@@ -75,23 +72,28 @@ Autolab3::Application.configure do
   # with SQLite, MySQL, and PostgreSQL)
   # config.active_record.auto_explain_threshold_in_seconds = 0.5
 
-  # Provide context to the email generator about the host
-  #config.action_mailer.default_url_options = {protocol: 'http', host: 'example.com' }
-
-  config.action_mailer.delivery_method = :sendmail
   config.action_mailer.perform_deliveries = true
   config.action_mailer.raise_delivery_errors = true
 
-  # Use a custom smtp server, like Mandrill
-  #config.action_mailer.smtp_settings = {
-  #  address:              'smtp.mandrillapp.com',
-  #  port:                 25,
-  #  enable_starttls_auto: true,
-  #  authentication:       'login',
-  #  user_name:            'MANDRILL_USERNAME',
-  #  password:             'MANDRILL_PASSWORD',
-  #  domain:               'example.com',
-  #}
+  # Provide context to the email generator about the host
+  config.action_mailer.default_url_options = {protocol: 'http', host: 'yourhost.com' }
+
+  # Use a custom smtp server, such as gmail, mailgun, sendgrid
+  config.action_mailer.smtp_settings = {
+    address:              'smtp.example.com',
+    port:                 25,
+    enable_starttls_auto: true,
+    authentication:       'login',
+    user_name:            'example',
+    password:             'example',
+    domain:               'example.com',
+  }
+
+  # default from 
+  ActionMailer::Base.default :from => '[email protected]'
+
+  # option for using sendmail
+  # config.action_mailer.delivery_method = :sendmail
 
   config.middleware.use ExceptionNotification::Rack,
     email: {

config/environments/production.rb.template

@@ -1,6 +1,6 @@
 This page details all the endpoints of the Autolab REST API.
 
-The client's access token should be included as a parameter to all endpoints. For details on obtaining access tokens, please see the [API Overview](/api-overview/)
+The client's access token should be included as a parameter to all endpoints. For details on obtaining access tokens, please see the [API Overview](/api-overview/).
 
 ## Routing
 

docs/api-interface.md

@@ -18,7 +18,7 @@ V1 of the API allows clients to:
 
 All endpoints of the Autolab API requires client authentication in the form of an access token. To obtain this access token, clients must obtain authorization from the user.
 
-Autolab API uses the standard [OAuth2](https://tools.ietf.org/html/rfc6749) [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1) for user authorization. For clients with no easy access to web browsers (e.g. console apps), an alternative [device flow](https://tools.ietf.org/html/draft-ietf-oauth-device-flow-07)-based authorization method is provided as well.
+Autolab API uses the standard <a href="https://tools.ietf.org/html/rfc6749" target="_blank">OAuth2</a> <a href="https://tools.ietf.org/html/rfc6749#section-4.1" target="_blank">Authorization Code Grant</a> for user authorization. For clients with no easy access to web browsers (e.g. console apps), an alternative <a href="https://tools.ietf.org/html/draft-ietf-oauth-device-flow-07" target="_blank">device flow</a>-based authorization method is provided as well.
 
 To understand how to authorize and unauthorize clients as a user, go to [Managing Authorized Apps](/api-managing-authorized-apps/)
 
@@ -38,9 +38,9 @@ The endpoint for obtaining user authorization is
 The endpoint for obtaning access tokens and refresh tokens is
 `oauth/token`
 
-[Section 4.1 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-4.1) details the parameters required and the response clients can expect from these endpoints.
+<a href="https://tools.ietf.org/html/rfc6749#section-4.1" target="_blank">Section 4.1 of RFC 6749</a> details the parameters required and the response clients can expect from these endpoints.
 
-Autolab API provides a refresh token with every new access token. Once the access token has expired, the client can use the refresh token to obtain a new access token, refresh token pair. Details are also provided in RFC 6749 [here](https://tools.ietf.org/html/rfc6749#section-6).
+Autolab API provides a refresh token with every new access token. Once the access token has expired, the client can use the refresh token to obtain a new access token, refresh token pair. Details are also provided in RFC 6749 <a href="https://tools.ietf.org/html/rfc6749#section-6" target="_blank">here</a>.
 
 ### Device Flow
 

docs/api-overview.md

@@ -1,13 +1,13 @@
 # Autolab Command Line Interface
 
-To help showcase the capabilities of the API, we developed autolab-cli: A first-party command line client that serves as both a practical tool for users of Autolab, as well as a reference design for developers intending to use the API in their own programs. The cli includes features like downloading and submitting assignments from the terminal, viewing problems, and getting submission feedback.
+To help showcase the capabilities of the [API](/api-overview), we developed autolab-cli: A first-party command line client that serves as both a practical tool for users of Autolab, as well as a reference design for developers intending to use the API in their own programs. The cli includes features like downloading and submitting assignments from the terminal, viewing problems, and getting submission feedback.
 
 !!! info "Note to CMU Students:"
     This cli binary has already been installed on the andrew machines as `autolab`.
 
 ## Obtaining authorization
 
-Make sure you have the cli installed by running `autolab` in your terminal. If you see the usage instructions you're good to go. Otherwise, ask your school admin to install the cli from the [Autolab CLI Repository](https://github.com/autolab/autolab-cli).
+Make sure you have the cli installed by running `autolab` in your terminal. If you see the usage instructions you're good to go. Otherwise, ask your school admin to install the cli from the <a href="https://github.com/autolab/autolab-cli" target="_blank">Autolab CLI Repository</a>.
 
 To setup autolab-cli with your Autolab account, run `autolab setup`. This will initiate a manual activation.
 
@@ -96,4 +96,4 @@ $ autolab <sub-command> -h
 
 This will reveal other flags you may be able to use with each command. For example, you can call all of the context-dependent commands outside of an assessment directory by providing the `<course_unique_name>:<asmt_unique_name>` pair.
 
-We hope this speeds up your workflow! If you find any problems, please file an issue on the [Autolab CLI Repository](https://github.com/autolab/autolab-cli).
+We hope this speeds up your workflow! If you find any problems, please file an issue on the <a href="https://github.com/autolab/autolab-cli" target="_blank">Autolab CLI Repository</a>.