{"id":44677317,"url":"https://github.com/specify/specify.github.io","last_synced_at":"2026-02-15T03:30:36.884Z","repository":{"id":225024671,"uuid":"764903063","full_name":"specify/specify.github.io","owner":"specify","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-15T21:01:07.000Z","size":15048,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-15T23:12:04.101Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/specify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-02-28T23:12:03.000Z","updated_at":"2025-09-15T21:00:46.000Z","dependencies_parsed_at":"2024-03-20T20:31:08.392Z","dependency_job_id":"c136baf4-9ee1-47eb-ab63-daf0a395e8ea","html_url":"https://github.com/specify/specify.github.io","commit_stats":null,"previous_names":["specify/specify.github.io"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/specify/specify.github.io","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specify%2Fspecify.github.io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specify%2Fspecify.github.io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specify%2Fspecify.github.io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specify%2Fspecify.github.io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/specify","download_url":"https://codeload.github.com/specify/specify.github.io/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specify%2Fspecify.github.io/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29466929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T01:01:38.065Z","status":"online","status_checked_at":"2026-02-15T02:00:07.449Z","response_time":118,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-15T03:30:36.255Z","updated_at":"2026-02-15T03:30:36.874Z","avatar_url":"https://github.com/specify.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Specify Internal Documentation\n\nThis repository is now ARCHIVED.  All documentation here is now available to SCC staff on the Speciforum.\n\n\nThis repository contains our internal documentation for Specify Collections Consortium staff.\n\nThis site uses [Sphinx](https://www.sphinx-doc.org/en/master/) as a framework and is built using `github-pages`. You can view the [deployment history here](https://github.com/specify/specify.github.io/deployments/github-pages).\n\n## Contribution Guidelines\n- Do **not commit** sensitive information. This is a public repository.\n- Docs that are useful or relevant to users of Specify should instead be pushed to the [**Speciforum**](discourse.specifysoftware.org), not this repository.\n- Docs added to this repository should be removed from their original location (e.g. Google Drive, ResFS, OneDrive, etc.) after it is committed.\n- Be kind, considerate, and thoughtful.\n\n## Setup and Installation\n\n### Install and Configure Sphinx\n\nCreate or activate a virtual Python environment for the project:\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\nInstall the requirements which include Sphinx and myst-parser (for Markdown parsing):\n\n```bash\npip install -r requirements-docs.txt\n```\n\nThe `requirements-docs.txt` file contains both Sphinx and myst-parser to handle ReStructuredText and Markdown formats.\n\n### Initial Sphinx Setup\n\nIf setting up Sphinx for the first time, create a directory to contain documentation (in our case, `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:\n\n```bash\ncd sphinx\nsphinx-quickstart\n```\n\nEdit the `conf.py` file similar to our existing [conf.py](sphinx/conf.py).\n\n## Run Locally\n\nTo run Sphinx locally and build the documentation:\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements-docs.txt\ncd sphinx\nmake html\n```\n\nEach time you make a change, you'll need to run `make html` again from the `sphinx` directory. You should see a list of warnings in the terminal each time to indicate potential issues in the repository. Run this prior to pushing to GitHub:\n\n```bash\nchecking consistency... /Users/g584f396/GitHub/specify.github.io/sphinx/aws/aws_authentication.rst: WARNING: document isn't included in any toctree [toc.not_included]\n```\n\nYou can access the built documentation by opening the `index.html` file in your browser (e.g. \n`file:///Users/g584f396/GitHub/specify.github.io/sphinx/_build/html/index.html`).\n\n## Writing and Editing Documentation\n\n### Documentation Format\n\nWrite all documents in ReStructuredText (.rst) or Markdown (.md) format. The requirements include both Sphinx and myst-parser to handle each format. Organize documents in logical subdirectories within the `sphinx` folder.\n\n### Important Guidelines\n\n- Each document must contain only one top-level title, which will be displayed in the Table of Contents\n- Any number of sub-level headings may be included in each document\n- Edit the `index.rst` file to include page names under the Table of Contents (toctree)\n- Include paths relative to the documentation directory, and filenames without extension\n- The `:maxdepth:` parameter indicates how many sublevels will be displayed in the Table of Contents\n- Only if there are very few pages should `:maxdepth:` be more than 1\n\n### Building and Testing\n\nIn the documentation directory, run the following to build pages locally and check formatting. The command will build documentation and print errors and warnings in the terminal output:\n\n```bash\nmake html\n```\n\n## GitHub Pages Publishing\n\n### Repository Setup\n\nThis repository uses GitHub Pages for automatic deployment. The site is published to https://specify.github.io/ using GitHub Actions.\n\n### GitHub Actions Configuration\n\nThe repository uses a GitHub Action configured in `.github/workflows/build_sphinx_docs.yml` to automatically build and deploy the documentation when changes are pushed to the main branch.\n\n### Deployment Process\n\n1. When code is pushed to GitHub, the GitHub Action runs automatically\n2. Sphinx builds the documentation\n3. The built site is deployed to the `gh-pages` branch\n4. GitHub Pages serves the content from this branch\n5. The site is available at https://specify.github.io/ within minutes\n\n\n## Contribute\n\nContribution for this repository is limited only to SCC staff.\n\n### Step-by-Step Contribution Process\n\n1. **Clone the repository**\n\n    ```bash\n    gh repo clone specify/specify.github.io\n    ```\n\n2. **Create a new document**\n   \n   Create a new `.md` or `.rst` file under the appropriate directory (e.g. `server_management`, `testing`, `security`, etc.) or create a new directory to begin a new category.\n\n    ```bash\n    ├── LICENSE\n    ├── README.md\n    ├── environment.yml\n    ├── requirements-docs.txt\n    └── sphinx\n        ├── Makefile\n        ├── asset_server\n        ├── aws\n        ├── conf.py\n        ├── dev_process\n        ├── dwc_alignment\n        ├── index.rst\n        ├── make.bat\n        ├── misc\n        ├── processes\n        ├── scripts\n        ├── security\n        ├── server_management\n        ├── software_desc\n        └── testing\n    ```\n\n    For example, to add `reports.md` to the repository under `server_management`:\n\n    ```bash\n    └── sphinx\n        └── server_management\n            ├── check_asset_usage.md\n            └── reports.md\n    ```\n\n3. **Add to Table of Contents**\n   \n   Add your document to the sidebar and homepage by editing the `index.rst` file in the `./sphinx/` directory under the appropriate category. Add the path to your file within that directory minus the file extension (no `.md` or `.rst`).\n\n    If the category you want does not yet exist, you can add a new one in the same format and structure as the others.\n\n    ```rst\n    .. toctree::\n       :maxdepth: 1\n       :caption: Server Management:\n\n       server_management/check_asset_usage\n       server_management/reports\n    ```\n\n4. **Preview and test locally**\n   \n   Before committing, preview, proofread, and double-check your document for accuracy:\n\n    ```bash\n    cd sphinx\n    make html\n    ```\n\n    Once saved, the file will be available at this URL pattern (after the base domain):\n\n    ```\n    /server_management/reports.html\n    ```\n\n5. **Commit and deploy**\n   \n   Save and commit to the `main` branch of this repository on GitHub. GitHub will automatically update the pages site (https://specify.github.io/) within minutes and the document will be available publicly.\n\n### Content Guidelines\n\n- Ensure your documentation follows the contribution guidelines at the top of this README\n- Remove documents from their original location (Google Drive, ResFS, OneDrive, etc.) after committing to this repository\n- Test your changes locally before pushing to ensure proper formatting and no build errors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecify%2Fspecify.github.io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspecify%2Fspecify.github.io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecify%2Fspecify.github.io/lists"}