Skip to content

Commit f11a8df

Browse files
Update README.md
1 parent 47180f9 commit f11a8df

File tree

1 file changed

+78
-1
lines changed

1 file changed

+78
-1
lines changed

README.md

Lines changed: 78 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,78 @@
1-
Welcome to Specify Developer Documentation
1+
# Specify Internal Documentation
2+
3+
This repository contains our internal documentation for Specify Collections Consortium staff.
4+
5+
This 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).
6+
7+
8+
9+
## Contribution Guidelines
10+
- Do **not commit** sensitive information. This is a public repository.
11+
- Docs that are useful or relevant to users of Specify should instead be pushed to the [**Speciforum**](discourse.specifysoftware.org), not this repository.
12+
- Docs added to this repository should be removed from their original location (e.g. Google Drive, ResFS, OneDrive, etc.) after it is committed.
13+
- Be kind, considerate, and thoughtful.
14+
15+
## Contribute
16+
17+
Contribution for this repository is limited only to SCC staff.
18+
19+
1. Clone the repository
20+
21+
```bash
22+
gh repo clone specify/specify.github.io
23+
```
24+
25+
2. 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.
26+
27+
```bash
28+
├── LICENSE
29+
├── README.md
30+
├── environment.yml
31+
├── requirements-docs.txt
32+
└── sphinx
33+
├── Makefile
34+
├── asset_server
35+
├── aws
36+
├── conf.py
37+
├── dev_process
38+
├── dwc_alignment
39+
├── index.rst
40+
├── make.bat
41+
├── misc
42+
├── processes
43+
├── scripts
44+
├── security
45+
├── server_management
46+
├── software_desc
47+
└── testing
48+
```
49+
50+
For example, I may want to add `reports.md` to the repository under `server_management`, so I would add this below like so:
51+
52+
```bash
53+
└── sphinx
54+
└── server_management
55+
├── check_asset_usage.md
56+
└── reports.md
57+
```
58+
59+
3. Preview, proofread, and double-check your document for accuracy. Once saved, the file will be available at this URL (after the base domain)
60+
61+
```
62+
/server_management/reports.html
63+
```
64+
65+
4. You can add this to the sidebar and homepage by adding it to the `index.rst` file in the `./sphinx/` directory under the appropriate category. You just need to add the path to your file within that directory minus the file extension (no `.md` or `.rst`).
66+
67+
If the category you want does not yet exist, you can add a new one in the same format and structure as the others.
68+
69+
```rst
70+
.. toctree::
71+
:maxdepth: 1
72+
:caption: Server Management:
73+
74+
server_management/check_asset_usage
75+
server_management/reports
76+
```
77+
78+
5. 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.

0 commit comments

Comments
 (0)