|
1 | 1 | # Introduction |
2 | 2 |
|
3 | | -This repository has been populated with a basic getting-started structure |
4 | | -that we can extend for the PQ code package project. |
| 3 | +Welcome to the pq-code-package documentation. |
5 | 4 |
|
6 | | -Some todos remain, see below for the list. |
| 5 | +In this version, only the **Contributing** section has been |
| 6 | +customized. |
7 | 7 |
|
8 | | -During the Hackathon we can hopefully start building this site. |
9 | | - |
10 | | - |
11 | | -## Configuration Updates |
12 | | - |
13 | | -### Project Logo |
14 | | - |
15 | | -Replace the file `docs/assets/project-logo.png` with the logo for your project. |
16 | | - |
17 | | -!!! tip |
18 | | - |
19 | | - White logos with a transparent background works best for the project logo. |
20 | | - |
21 | | -!!! warning Logo Filename |
22 | | - |
23 | | - If you use a different name than `project-logo.png`, you will also need to update the `mkdocs.yml` file to replace the `theme.logo` tag to reflect the correct filename. Example: |
24 | | - |
25 | | - !!! example |
26 | | - ``` yaml |
27 | | - theme: |
28 | | - logo: assets/name-of-logo-file.png |
29 | | - ``` |
30 | | - |
31 | | -### Project Icon |
32 | | - |
33 | | -Replace the file `docs/assets/project-icon.png` with the icon for your project. |
34 | | - |
35 | | -!!! tip |
36 | | - |
37 | | - Color or dark icons works best for the project icon. |
38 | | - |
39 | | -!!! warning Icon Filename |
40 | | - |
41 | | - If you use a different name than `project-icon.png`, you will also need to update the `mkdocs.yml` file to replace the `theme.favicon` tag to reflect the correct filename. Example: |
42 | | - |
43 | | - !!! example |
44 | | - ``` yaml |
45 | | - theme: |
46 | | - favicon: assets/name-of-icon-file.png |
47 | | - ``` |
48 | | - |
49 | | -## Documentation Updates |
50 | | - |
51 | | -### Overall |
52 | | - |
53 | | -Find and replace the use of `_PROJECT_` with the name of your project in all markdown files and the `mkdocs.yml` file. |
54 | | - |
55 | | -### Introduction |
56 | | - |
57 | | -Update the `docs/index.md` file to provide an introduction to the project. |
58 | | - |
59 | | -### Concepts |
60 | | - |
61 | | -The `docs/concepts` directory will contain information about the relevant concepts for your project. Currently there are placeholders for three concepts (`docs/concepts/concepts-[123].md`). You can remove these files and add a separate markdown file for each of the relevant concepts. Then modify the `mkdocs.yml` `nav` section to reflect the concept name and pointer to the concept. The relevant portion of the `mkdocs.yml` file is: |
62 | | - |
63 | | -!!! example |
64 | | - ``` yaml |
65 | | - nav: |
66 | | - - Concepts: |
67 | | - - Concept 1: concepts/concept-1.md |
68 | | - - Concept 2: concepts/concept-2.md |
69 | | - - Concept 3: concepts/concept-3.md |
70 | | - ``` |
71 | | - |
72 | | -### Getting Started |
73 | | - |
74 | | -The files in the Getting Started topic are intended to help people get up and running with your project. |
75 | | - |
76 | | -* Installation (`docs/getting-started/installation.md`) - provide details on how to install the project. |
77 | | -* Running (`docs/getting-started/running.md`) - provide details on how to run the project. |
78 | | - |
79 | | -### Tutorials |
80 | | - |
81 | | -The `docs/tutorials` directory will contain tutorials that the use can use to learn about your project. There is an introduction page that you can use to describe your tutorials at a high level. In addition, there are placeholders for three tutorials (`docs/tutorials/tutorials-[123].md`). You can remove the placeholder files and add a separate markdown file for each of the relevant tutorials. Then modify the `mkdocs.yml` `nav` section to reflect the tutorial name, and pointer to the tutorial. The relevant portion of the `mkdocs.yml` file is: |
82 | | - |
83 | | -!!! example |
84 | | - ``` yaml |
85 | | - nav: |
86 | | - - Tutorials: |
87 | | - - Introduction: tutorials/index.md |
88 | | - - Tutorial 1: tutorials/tutorial-1.md |
89 | | - - Tutorial 2: tutorials/tutorial-2.md |
90 | | - - Tutorial 3: tutorials/tutorial-3.md |
91 | | - ``` |
92 | | -### Guides |
93 | | - |
94 | | -In the Guides section, there are three placeholders: |
95 | | -1. Operations (`docs/guides/operations.md`) - used to guide an operator of your project through critical tasks. |
96 | | -2. Developers (`docs/guides/developers.md`) - used to guide a developer using your project through critical tasks. |
97 | | -3. Upgrading (`docs/guides/upgrading.md`) - used to guide someone through upgrading from one version of your project to another. |
98 | | - |
99 | | -!!! note |
100 | | - The placeholders are not all inclusive. Please add any other reference material that is needed and update the `mkdocs.yml` `nav` section to ensure these references show up on the documentation site. |
101 | | - |
102 | | -### References |
103 | | - |
104 | | -In the References section, there are three placeholders: |
105 | | - |
106 | | -1. Architecture (`docs/references/architecture.md`) - describe the architecture for the project in this file. |
107 | | -2. Commands (`docs/references/commands.md`) - describe the different commands that are available for running the project. |
108 | | -3. Roadmap (`docs/references/roadmap.md`) - describe the roadmap for the project. |
109 | | - |
110 | | -!!! note |
111 | | - The placeholders are not all inclusive. Please add any other reference material that is needed and update the `mkdocs.yml` `nav` section to ensure these references show up on the documentation site. |
112 | | - |
113 | | -### Contributing |
114 | | - |
115 | | -The files in the Contributing topic are intended to help people who are interested in contributing to your project. |
116 | | - |
117 | | -!!! note |
118 | | - Sample text has been provided in these files. Feel free to modify to fit your project. |
119 | | - |
120 | | -* How to Contribute (`docs/contributing/how-to-contribute.md`) - provide details on how to contribute to the project. |
121 | | -* Reporting a Bug (`docs/contributing/reporting-a-bug.md`) - provide details on how to report a bug. |
122 | | -* Requesting a Change (`docs/contributing/requesting-a-change.md`) - provide details on how to request a change. |
123 | | -* Asking a Question (`docs/contributing/asking-a-question.md`) - provide details on how and where to ask questions. |
124 | | - |
125 | | -### FAQs |
126 | | - |
127 | | -There is a placeholder (`docs/faqs.md`) for including any frequently asked questions about the project. Please update this document whenever you come across a frequently asked question. |
128 | | - |
129 | | -### Glossary |
130 | | - |
131 | | -There is a placeholder (`docs/glossary.md`) for capturing terms that are used in the documentation and with relation to the project. Please update the glossary to include relevant terms and definitions. |
0 commit comments