formatting

sphinx/asset_server/asset_config_files.md

@@ -1,6 +1,6 @@
-## Specify 7 Docker Config Example
+# Specify 7 Docker Config Example
 
-### Example defaults.env
+## Example defaults.env
 
 ```
 DATABASE_HOST=10.133.58.98
@@ -18,7 +18,7 @@ LOG_LEVEL=WARNING
 SP7_DEBUG=false
 ```
 
-### Example docker-compose.yml
+## Example docker-compose.yml
 
 ```yml
 version: '3.7'
@@ -343,7 +343,7 @@ volumes:
   static-files-eurl:
 ```
 
-### Example nginx.conf
+## Example nginx.conf
 
 ```
 server {

sphinx/asset_server/asset_server_config.md

@@ -1,3 +1,5 @@
+# Asset Server Configuration
+
 Here is an asset server configuration example with the latest image `specifyconsortium/specify-asset-service:connection_fix`.
 I spun up a server with the following config and got it working `assets-docker.specifycloud.org/web_asset_store.xml`
 Make sure to configure your dns record to the IP address of your server.

sphinx/asset_server/asset_server_setup.md

@@ -1,4 +1,4 @@
-## EC2 Non-Dockerized Build
+# EC2 Non-Dockerized Build
 
 [asset_server_setup.sh](../scripts/asset_server_setup.sh) to initialize the asset server.
 

sphinx/asset_server/hybrid_asset_server_setup.md

@@ -1,4 +1,5 @@
+# Hybrid Asset Server Setup
 
-Instructions to setup an asset server with 
+Bash script to setup an asset server:  
 
 [hybrid_asset_server_setup.sh](../scripts/hybrid_asset_server_setup.sh)

sphinx/aws/specify_cloud_graviton_setup.md

@@ -1,3 +1,5 @@
+# Specify Cloud Graviton Setup
+
 Commands for running on ubuntu 20.04 arm64
 See `~/git/specify-aws-specify7-mosti-in-one-lite/docker-entrypoint.sh` for latest
 ```bash

sphinx/dev_process/project_docs.rst

@@ -0,0 +1,80 @@
+Project (Github pages) documentation
+############################################
+
+Install Configure Sphinx
+=============================
+
+Create or activate a virtual python environment for the project::
+
+  python3 -m venv venv
+  ./venv/bin/activate
+
+Create a requirements-doc.txt file with sphinx and myst-parser (for Markdown parsing)
+like `requirements-docs.txt <../../requirements-docs.txt>`_, then install the
+requirements::
+
+  pip install -r requirements-docs.txt
+
+Create a directory to contain documentation (in our example, **sphinx**), cd to that directory,
+then run sphinx-quickstart.  This will create the files conf.py, index.rst, and make.bat.
+It will also create a destination directory (the default is **_build**) for generated
+html::
+
+  cd sphinx
+  sphinx-quickstart
+
+Edit the conf.py file similar to
+`conf.py <../conf.py>`_
+
+
+Edit Documentation and View
+=============================
+
+Add documentation in the documentation directory.  Organize in subdirectories where
+logical.
+
+Edit the index.rst file to include page names under the Table of Contents (toctree).
+These should include paths relative to the documentation directory, and filenames
+without extension, similar to
+`index.rst <../index.rst>`_.
+
+In the documentation directory, run the following to build pages locally and check
+formatting::
+
+  make html
+
+Publish as Github Pages Site
+================================
+
+On Github, Create Repository for Pages site
+-----------------------------------------------
+
+https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site
+
+Create a new or use an existing github.io repository for the user/organization
+containing this repository to be publicly documented.
+
+<organization>.github.io
+
+If the organization site already exists, you can publish github pages to a subdirectory
+under the existing site, i.e. <organization>.github.io/<project>
+
+Go to settings of the new repository, under Code and Automation, select Pages
+
+For Github Action, add YAML configuration files
+----------------------------------------------------
+
+Create a yaml file to initiate a github action with a file in ./.github/workflows, like
+`build_sphinx_docs.yml <../../.github/workflows/build_sphinx_docs.yml>`_.
+
+Optional?: Add `<.readthedocs.yaml <../../.readthedocs.yaml>`_ and
+`environment.yml <../../environment.yml>`_ for the build.
+
+Set Pages Site to branch created by Github action
+--------------------------------------------------------
+
+After the code is pushed to github, and the action completes successfully, a branch will
+be created.  In the example build_sphinx_docs.yml, it is named gh-pages.  Under the
+Settings/Code and Automation/Pages form, choose the new branch (in our example,
+**gh-pages**)
+

sphinx/index.rst

@@ -10,14 +10,23 @@ Welcome to Specify Developer documentation!
    aws/aws_specify_cloud_setup
    aws/client_migration_notes
    aws/ec2_rds_specify7_setup
-   aws/specify7_ecs_most-in-one
    aws/specify_cloud_graviton_setup
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Asset Server:
+
+   asset_server/asset_config_files
+   asset_server/asset_server_config
+   asset_server/asset_server_setup
+   asset_server/hybrid_asset_server_setup
+
 .. toctree::
    :maxdepth: 1
    :caption: Internal Processes:
 
    dev_process/specify_processes
+   dev_process/project_docs
 
 .. toctree::
    :maxdepth: 1