docs(wiki): added copyable prompt to generate wiki in doc-forge wiki
This commit is contained in:
@@ -764,8 +764,530 @@ OpenAPI-based API docs.</p>
|
||||
<h2 id="related-resources">🔗 Related Resources</h2>
|
||||
<ul>
|
||||
<li><strong>Source Code:</strong> the <code>doc-forge</code> repository</li>
|
||||
<li><strong>Wiki Kind:</strong> hand-written content lives in <code>docs/wiki/</code></li>
|
||||
<li><strong>MCP Bundle:</strong> generated by <code>doc-forge build --mcp --module docforge</code> into <code>docs/mcp/</code></li>
|
||||
<li><strong>Wiki Kind:</strong> hand-written content lives in <code>docs/wiki/</code> or use the prompt mentioned below
|
||||
<div class="language-markdown highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1"> 1</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-2"> 2</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-3"> 3</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-4"> 4</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-5"> 5</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-6"> 6</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-7"> 7</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-8"> 8</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-9"> 9</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-10"> 10</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-11"> 11</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-12"> 12</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-13"> 13</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-14"> 14</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-15"> 15</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-16"> 16</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-17"> 17</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-18"> 18</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-19"> 19</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-20"> 20</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-21"> 21</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-22"> 22</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-23"> 23</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-24"> 24</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-25"> 25</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-26"> 26</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-27"> 27</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-28"> 28</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-29"> 29</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-30"> 30</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-31"> 31</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-32"> 32</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-33"> 33</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-34"> 34</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-35"> 35</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-36"> 36</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-37"> 37</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-38"> 38</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-39"> 39</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-40"> 40</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-41"> 41</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-42"> 42</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-43"> 43</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-44"> 44</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-45"> 45</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-46"> 46</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-47"> 47</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-48"> 48</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-49"> 49</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-50"> 50</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-51"> 51</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-52"> 52</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-53"> 53</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-54"> 54</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-55"> 55</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-56"> 56</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-57"> 57</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-58"> 58</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-59"> 59</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-60"> 60</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-61"> 61</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-62"> 62</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-63"> 63</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-64"> 64</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-65"> 65</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-66"> 66</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-67"> 67</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-68"> 68</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-69"> 69</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-70"> 70</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-71"> 71</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-72"> 72</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-73"> 73</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-74"> 74</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-75"> 75</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-76"> 76</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-77"> 77</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-78"> 78</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-79"> 79</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-80"> 80</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-81"> 81</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-82"> 82</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-83"> 83</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-84"> 84</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-85"> 85</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-86"> 86</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-87"> 87</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-88"> 88</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-89"> 89</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-90"> 90</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-91"> 91</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-92"> 92</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-93"> 93</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-94"> 94</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-95"> 95</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-96"> 96</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-97"> 97</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-98"> 98</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-99"> 99</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-100">100</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-101">101</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-102">102</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-103">103</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-104">104</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-105">105</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-106">106</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-107">107</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-108">108</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-109">109</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-110">110</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-111">111</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-112">112</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-113">113</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-114">114</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-115">115</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-116">116</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-117">117</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-118">118</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-119">119</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-120">120</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-121">121</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-122">122</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-123">123</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-124">124</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-125">125</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-126">126</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-127">127</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-128">128</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-129">129</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-130">130</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-131">131</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-132">132</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-133">133</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-134">134</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-135">135</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-136">136</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-137">137</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-138">138</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-139">139</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-140">140</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-141">141</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-142">142</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-143">143</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-144">144</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-145">145</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-146">146</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-147">147</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-148">148</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-149">149</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-150">150</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-151">151</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-152">152</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-153">153</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-154">154</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-155">155</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-156">156</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-157">157</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-158">158</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-159">159</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-160">160</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-161">161</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-162">162</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-163">163</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-164">164</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-165">165</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-166">166</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-167">167</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-168">168</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-169">169</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-170">170</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-171">171</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-172">172</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-173">173</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-174">174</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-175">175</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-176">176</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-177">177</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-178">178</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-179">179</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-180">180</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-181">181</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-182">182</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-183">183</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-184">184</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-185">185</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-186">186</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-187">187</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-188">188</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-189">189</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-190">190</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-191">191</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-192">192</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-193">193</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-194">194</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-195">195</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-196">196</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-197">197</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-198">198</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-199">199</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-200">200</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-201">201</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-202">202</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-203">203</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-204">204</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-205">205</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-206">206</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-207">207</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-208">208</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-209">209</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-210">210</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-211">211</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-212">212</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-213">213</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-214">214</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-215">215</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-216">216</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-217">217</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-218">218</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-219">219</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-220">220</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-221">221</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-222">222</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-223">223</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-224">224</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-225">225</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-226">226</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-227">227</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-228">228</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-229">229</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-230">230</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-231">231</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-232">232</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-233">233</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-234">234</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-235">235</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-236">236</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-237">237</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-238">238</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-239">239</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-240">240</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-241">241</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-242">242</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-243">243</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-244">244</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-245">245</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-246">246</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-247">247</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-248">248</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-249">249</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-250">250</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-251">251</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-252">252</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-253">253</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-254">254</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-255">255</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-256">256</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-257">257</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-258">258</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-259">259</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-260">260</a></span>
|
||||
<span class="normal"><a href="#__codelineno-0-261">261</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="gh"># AGENTS.md — Wiki Authoring Guide (Aetoskia)</span>
|
||||
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a>
|
||||
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3"></a>This file instructs AI agents how to create, extend, and maintain the wiki
|
||||
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4"></a>(<span class="sb">`docs/wiki/**`</span>) for any Aetoskia repository. The reference implementation is
|
||||
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5"></a><span class="sb">`mongo-ops`</span> — its wiki went through several revisions to reach the structure
|
||||
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6"></a>below and should be treated as the canonical example.
|
||||
</span><span id="__span-0-7"><a id="__codelineno-0-7" name="__codelineno-0-7"></a>
|
||||
</span><span id="__span-0-8"><a id="__codelineno-0-8" name="__codelineno-0-8"></a>---
|
||||
</span><span id="__span-0-9"><a id="__codelineno-0-9" name="__codelineno-0-9"></a>
|
||||
</span><span id="__span-0-10"><a id="__codelineno-0-10" name="__codelineno-0-10"></a><span class="gu">## 1. Doc model — know the two sources of truth</span>
|
||||
</span><span id="__span-0-11"><a id="__codelineno-0-11" name="__codelineno-0-11"></a>
|
||||
</span><span id="__span-0-12"><a id="__codelineno-0-12" name="__codelineno-0-12"></a>Every repo keeps two distinct kinds of documentation that must <span class="gs">**not**</span> bleed
|
||||
</span><span id="__span-0-13"><a id="__codelineno-0-13" name="__codelineno-0-13"></a>into each other:
|
||||
</span><span id="__span-0-14"><a id="__codelineno-0-14" name="__codelineno-0-14"></a>
|
||||
</span><span id="__span-0-15"><a id="__codelineno-0-15" name="__codelineno-0-15"></a>| Kind | Source | Where | Audience |
|
||||
</span><span id="__span-0-16"><a id="__codelineno-0-16" name="__codelineno-0-16"></a>|-------------------|-----------------------|------------------------------------------|------------------------------------|
|
||||
</span><span id="__span-0-17"><a id="__codelineno-0-17" name="__codelineno-0-17"></a>| <span class="gs">**Wiki**</span> | Hand-written markdown | <span class="sb">`docs/wiki/**`</span> | Humans (how-to, examples, testing) |
|
||||
</span><span id="__span-0-18"><a id="__codelineno-0-18" name="__codelineno-0-18"></a>| <span class="gs">**API reference**</span> | Docstrings (GSDFC) | Generated → <span class="sb">`docs/lib/**`</span>, <span class="sb">`docs/mcp/**`</span> | Consumers (exact contracts) |
|
||||
</span><span id="__span-0-19"><a id="__codelineno-0-19" name="__codelineno-0-19"></a>
|
||||
</span><span id="__span-0-20"><a id="__codelineno-0-20" name="__codelineno-0-20"></a>Rules:
|
||||
</span><span id="__span-0-21"><a id="__codelineno-0-21" name="__codelineno-0-21"></a>
|
||||
</span><span id="__span-0-22"><a id="__codelineno-0-22" name="__codelineno-0-22"></a><span class="k">-</span><span class="w"> </span>The wiki is written <span class="gs">**for humans**</span> — how-to guides, recipes, and testing
|
||||
</span><span id="__span-0-23"><a id="__codelineno-0-23" name="__codelineno-0-23"></a> patterns. It is never generated.
|
||||
</span><span id="__span-0-24"><a id="__codelineno-0-24" name="__codelineno-0-24"></a><span class="k">-</span><span class="w"> </span>API contracts (signatures, parameter types, exact behavior) live in the
|
||||
</span><span id="__span-0-25"><a id="__codelineno-0-25" name="__codelineno-0-25"></a> docstrings and the machine-readable bundle under <span class="sb">`docs/mcp/`</span>. <span class="gs">**Never**</span>
|
||||
</span><span id="__span-0-26"><a id="__codelineno-0-26" name="__codelineno-0-26"></a> duplicate full API documentation in the wiki — link to the lib site instead.
|
||||
</span><span id="__span-0-27"><a id="__codelineno-0-27" name="__codelineno-0-27"></a><span class="k">-</span><span class="w"> </span>If a page starts to drift into contract territory, cut it down to usage and
|
||||
</span><span id="__span-0-28"><a id="__codelineno-0-28" name="__codelineno-0-28"></a> point at <span class="sb">`docs/lib/`</span>.
|
||||
</span><span id="__span-0-29"><a id="__codelineno-0-29" name="__codelineno-0-29"></a><span class="k">-</span><span class="w"> </span>This doc model is stated on every index page as a blockquote; keep it there:
|
||||
</span><span id="__span-0-30"><a id="__codelineno-0-30" name="__codelineno-0-30"></a><span class="k"> > </span><span class="ge">**Doc model:** this wiki is written for humans — how‑to guides, examples,</span>
|
||||
</span><span id="__span-0-31"><a id="__codelineno-0-31" name="__codelineno-0-31"></a><span class="k"> > </span><span class="ge">and testing recipes. The authoritative API contracts live in the code</span>
|
||||
</span><span id="__span-0-32"><a id="__codelineno-0-32" name="__codelineno-0-32"></a><span class="k"> > </span><span class="ge">(docstrings) and the machine‑readable bundle under `docs/mcp/`.</span>
|
||||
</span><span id="__span-0-33"><a id="__codelineno-0-33" name="__codelineno-0-33"></a>
|
||||
</span><span id="__span-0-34"><a id="__codelineno-0-34" name="__codelineno-0-34"></a>---
|
||||
</span><span id="__span-0-35"><a id="__codelineno-0-35" name="__codelineno-0-35"></a>
|
||||
</span><span id="__span-0-36"><a id="__codelineno-0-36" name="__codelineno-0-36"></a><span class="gu">## 2. Directory layout & file naming</span>
|
||||
</span><span id="__span-0-37"><a id="__codelineno-0-37" name="__codelineno-0-37"></a>
|
||||
</span><span id="__span-0-38"><a id="__codelineno-0-38" name="__codelineno-0-38"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-39"><a id="__codelineno-0-39" name="__codelineno-0-39"></a><span class="sb">docs/wiki/</span>
|
||||
</span><span id="__span-0-40"><a id="__codelineno-0-40" name="__codelineno-0-40"></a><span class="sb">├── index.md # site Home</span>
|
||||
</span><span id="__span-0-41"><a id="__codelineno-0-41" name="__codelineno-0-41"></a><span class="sb">├── 01_overview.md</span>
|
||||
</span><span id="__span-0-42"><a id="__codelineno-0-42" name="__codelineno-0-42"></a><span class="sb">├── 02_components.md</span>
|
||||
</span><span id="__span-0-43"><a id="__codelineno-0-43" name="__codelineno-0-43"></a><span class="sb">├── 03_use_cases/ # nested directory → nav group</span>
|
||||
</span><span id="__span-0-44"><a id="__codelineno-0-44" name="__codelineno-0-44"></a><span class="sb">│ ├── 01_basic_crud.md</span>
|
||||
</span><span id="__span-0-45"><a id="__codelineno-0-45" name="__codelineno-0-45"></a><span class="sb">│ ├── 02_custom_repo.md</span>
|
||||
</span><span id="__span-0-46"><a id="__codelineno-0-46" name="__codelineno-0-46"></a><span class="sb">│ └── ...</span>
|
||||
</span><span id="__span-0-47"><a id="__codelineno-0-47" name="__codelineno-0-47"></a><span class="sb">├── 04_best_practices.md</span>
|
||||
</span><span id="__span-0-48"><a id="__codelineno-0-48" name="__codelineno-0-48"></a><span class="sb">├── 06_error_handling.md</span>
|
||||
</span><span id="__span-0-49"><a id="__codelineno-0-49" name="__codelineno-0-49"></a><span class="sb">└── 07_testing_example.md</span>
|
||||
</span><span id="__span-0-50"><a id="__codelineno-0-50" name="__codelineno-0-50"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-51"><a id="__codelineno-0-51" name="__codelineno-0-51"></a>
|
||||
</span><span id="__span-0-52"><a id="__codelineno-0-52" name="__codelineno-0-52"></a><span class="k">-</span><span class="w"> </span>Location: <span class="sb">`docs/wiki/`</span> (hand-written only).
|
||||
</span><span id="__span-0-53"><a id="__codelineno-0-53" name="__codelineno-0-53"></a><span class="k">-</span><span class="w"> </span>File names: <span class="sb">`NN_snake_case_name.md`</span> with a <span class="gs">**zero-padded two-digit**</span> numeric
|
||||
</span><span id="__span-0-54"><a id="__codelineno-0-54" name="__codelineno-0-54"></a> prefix. e.g. <span class="sb">`01_overview.md`</span>, <span class="sb">`03_use_cases/07_caching.md`</span>.
|
||||
</span><span id="__span-0-55"><a id="__codelineno-0-55" name="__codelineno-0-55"></a><span class="k">-</span><span class="w"> </span>Top-level pages use <span class="sb">`NN_name.md`</span> directly. High-volume sections get their own
|
||||
</span><span id="__span-0-56"><a id="__codelineno-0-56" name="__codelineno-0-56"></a> directory, e.g. <span class="sb">`03_use_cases/NN_name.md`</span> (nav group "Use Cases").
|
||||
</span><span id="__span-0-57"><a id="__codelineno-0-57" name="__codelineno-0-57"></a><span class="k">-</span><span class="w"> </span><span class="gs">**No frontmatter.**</span> Every file opens directly with an H1 <span class="sb">`# Title`</span>.
|
||||
</span><span id="__span-0-58"><a id="__codelineno-0-58" name="__codelineno-0-58"></a><span class="k">-</span><span class="w"> </span>Navigation labels are short human titles set explicitly in
|
||||
</span><span id="__span-0-59"><a id="__codelineno-0-59" name="__codelineno-0-59"></a> <span class="sb">`docs/mkdocs.wiki.yml`</span> (title case) — often <span class="gs">**shorter**</span> than the page H1.
|
||||
</span><span id="__span-0-60"><a id="__codelineno-0-60" name="__codelineno-0-60"></a> Example: nav label <span class="sb">`Basic CRUD`</span> vs page H1 <span class="sb">`Use Case 1: Basic FastAPI CRUD API`</span>.
|
||||
</span><span id="__span-0-61"><a id="__codelineno-0-61" name="__codelineno-0-61"></a> Never use the raw filename slug as the label.
|
||||
</span><span id="__span-0-62"><a id="__codelineno-0-62" name="__codelineno-0-62"></a><span class="k">-</span><span class="w"> </span>Renumbering: prefixes order pages. When inserting a page, pick the next
|
||||
</span><span id="__span-0-63"><a id="__codelineno-0-63" name="__codelineno-0-63"></a> number in the relevant group (subgroup numbers stay grouped).
|
||||
</span><span id="__span-0-64"><a id="__codelineno-0-64" name="__codelineno-0-64"></a>
|
||||
</span><span id="__span-0-65"><a id="__codelineno-0-65" name="__codelineno-0-65"></a>---
|
||||
</span><span id="__span-0-66"><a id="__codelineno-0-66" name="__codelineno-0-66"></a>
|
||||
</span><span id="__span-0-67"><a id="__codelineno-0-67" name="__codelineno-0-67"></a><span class="gu">## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth</span>
|
||||
</span><span id="__span-0-68"><a id="__codelineno-0-68" name="__codelineno-0-68"></a>
|
||||
</span><span id="__span-0-69"><a id="__codelineno-0-69" name="__codelineno-0-69"></a>Every wiki page <span class="gs">**must**</span> be wired into the nav defined in
|
||||
</span><span id="__span-0-70"><a id="__codelineno-0-70" name="__codelineno-0-70"></a><span class="sb">`docs/mkdocs.wiki.yml`</span>. If a page is not in the nav, it is orphaned.
|
||||
</span><span id="__span-0-71"><a id="__codelineno-0-71" name="__codelineno-0-71"></a>
|
||||
</span><span id="__span-0-72"><a id="__codelineno-0-72" name="__codelineno-0-72"></a><span class="k">-</span><span class="w"> </span>The <span class="sb">`nav:`</span> block mirrors the directory tree; directories become nested
|
||||
</span><span id="__span-0-73"><a id="__codelineno-0-73" name="__codelineno-0-73"></a> groups.
|
||||
</span><span id="__span-0-74"><a id="__codelineno-0-74" name="__codelineno-0-74"></a><span class="k">-</span><span class="w"> </span>When a section has many pages, group them <span class="gs">**by theme**</span> into nested
|
||||
</span><span id="__span-0-75"><a id="__codelineno-0-75" name="__codelineno-0-75"></a> subgroups. mongo-ops groups its use cases into:
|
||||
</span><span id="__span-0-76"><a id="__codelineno-0-76" name="__codelineno-0-76"></a> <span class="sb">`Getting Started`</span>, <span class="sb">`Data & Queries`</span>, <span class="sb">`Caching`</span>, <span class="sb">`Population`</span>,
|
||||
</span><span id="__span-0-77"><a id="__codelineno-0-77" name="__codelineno-0-77"></a> <span class="sb">`Advanced Usage`</span>.
|
||||
</span><span id="__span-0-78"><a id="__codelineno-0-78" name="__codelineno-0-78"></a><span class="k">-</span><span class="w"> </span>Keep <span class="sb">`index.md`</span>'s <span class="gs">**Documentation Structure**</span> table in sync with the nav —
|
||||
</span><span id="__span-0-79"><a id="__codelineno-0-79" name="__codelineno-0-79"></a> it is the human-facing version of the same TOC. Every nav entry needs a row
|
||||
</span><span id="__span-0-80"><a id="__codelineno-0-80" name="__codelineno-0-80"></a> (or nested bullet group) there.
|
||||
</span><span id="__span-0-81"><a id="__codelineno-0-81" name="__codelineno-0-81"></a><span class="k">-</span><span class="w"> </span>Nav label = human title (title case), not the filename slug.
|
||||
</span><span id="__span-0-82"><a id="__codelineno-0-82" name="__codelineno-0-82"></a>
|
||||
</span><span id="__span-0-83"><a id="__codelineno-0-83" name="__codelineno-0-83"></a>---
|
||||
</span><span id="__span-0-84"><a id="__codelineno-0-84" name="__codelineno-0-84"></a>
|
||||
</span><span id="__span-0-85"><a id="__codelineno-0-85" name="__codelineno-0-85"></a><span class="gu">## 4. Page anatomy</span>
|
||||
</span><span id="__span-0-86"><a id="__codelineno-0-86" name="__codelineno-0-86"></a>
|
||||
</span><span id="__span-0-87"><a id="__codelineno-0-87" name="__codelineno-0-87"></a><span class="gu">### 4.1 `index.md` (Home)</span>
|
||||
</span><span id="__span-0-88"><a id="__codelineno-0-88" name="__codelineno-0-88"></a>
|
||||
</span><span id="__span-0-89"><a id="__codelineno-0-89" name="__codelineno-0-89"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-90"><a id="__codelineno-0-90" name="__codelineno-0-90"></a><span class="sb"># 🧩 <package> — <slogan></span>
|
||||
</span><span id="__span-0-91"><a id="__codelineno-0-91" name="__codelineno-0-91"></a><span class="sb"><one-paragraph pitch></span>
|
||||
</span><span id="__span-0-92"><a id="__codelineno-0-92" name="__codelineno-0-92"></a>
|
||||
</span><span id="__span-0-93"><a id="__codelineno-0-93" name="__codelineno-0-93"></a><span class="sb">> **Doc model:** … (see §1)</span>
|
||||
</span><span id="__span-0-94"><a id="__codelineno-0-94" name="__codelineno-0-94"></a>
|
||||
</span><span id="__span-0-95"><a id="__codelineno-0-95" name="__codelineno-0-95"></a><span class="sb">---</span>
|
||||
</span><span id="__span-0-96"><a id="__codelineno-0-96" name="__codelineno-0-96"></a>
|
||||
</span><span id="__span-0-97"><a id="__codelineno-0-97" name="__codelineno-0-97"></a><span class="sb">## 🚀 Key Features (bullet list, emoji per feature)</span>
|
||||
</span><span id="__span-0-98"><a id="__codelineno-0-98" name="__codelineno-0-98"></a><span class="sb">## 📦 Installation (code blocks: internal PyPI, extras, local source)</span>
|
||||
</span><span id="__span-0-99"><a id="__codelineno-0-99" name="__codelineno-0-99"></a><span class="sb">## 📁 Documentation Structure (table = TOC, mirrors nav exactly)</span>
|
||||
</span><span id="__span-0-100"><a id="__codelineno-0-100" name="__codelineno-0-100"></a><span class="sb">## 🔗 Related Resources (bullets: source repo, internal PyPI, CI)</span>
|
||||
</span><span id="__span-0-101"><a id="__codelineno-0-101" name="__codelineno-0-101"></a><span class="sb">---</span>
|
||||
</span><span id="__span-0-102"><a id="__codelineno-0-102" name="__codelineno-0-102"></a><span class="sb">© Aetoskia Internal — `<package>` <version></span>
|
||||
</span><span id="__span-0-103"><a id="__codelineno-0-103" name="__codelineno-0-103"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-104"><a id="__codelineno-0-104" name="__codelineno-0-104"></a>
|
||||
</span><span id="__span-0-105"><a id="__codelineno-0-105" name="__codelineno-0-105"></a><span class="gu">### 4.2 Overview page (`01_*`)</span>
|
||||
</span><span id="__span-0-106"><a id="__codelineno-0-106" name="__codelineno-0-106"></a>
|
||||
</span><span id="__span-0-107"><a id="__codelineno-0-107" name="__codelineno-0-107"></a><span class="k">-</span><span class="w"> </span>Opens with <span class="sb">`# Library Overview`</span>, one sentence about what the library does,
|
||||
</span><span id="__span-0-108"><a id="__codelineno-0-108" name="__codelineno-0-108"></a> then a line stating the page builds the mental model.
|
||||
</span><span id="__span-0-109"><a id="__codelineno-0-109" name="__codelineno-0-109"></a><span class="k">-</span><span class="w"> </span>Sections: <span class="sb">`## 🏗️ Architecture`</span> (ASCII diagram + numbered layer list),
|
||||
</span><span id="__span-0-110"><a id="__codelineno-0-110" name="__codelineno-0-110"></a> <span class="sb">`## 🔄 Lifecycle Rules`</span> (table: step / call / why),
|
||||
</span><span id="__span-0-111"><a id="__codelineno-0-111" name="__codelineno-0-111"></a> <span class="sb">`## 🧭 Which … Should You Use?`</span> (decision table).
|
||||
</span><span id="__span-0-112"><a id="__codelineno-0-112" name="__codelineno-0-112"></a><span class="k">-</span><span class="w"> </span>Ends with <span class="sb">`## ➡️ Read Next`</span> (cross-links to the next pages to read).
|
||||
</span><span id="__span-0-113"><a id="__codelineno-0-113" name="__codelineno-0-113"></a>
|
||||
</span><span id="__span-0-114"><a id="__codelineno-0-114" name="__codelineno-0-114"></a><span class="gu">### 4.3 Components page (`02_*`)</span>
|
||||
</span><span id="__span-0-115"><a id="__codelineno-0-115" name="__codelineno-0-115"></a>
|
||||
</span><span id="__span-0-116"><a id="__codelineno-0-116" name="__codelineno-0-116"></a><span class="k">-</span><span class="w"> </span>Validated reference for the public API surface — describes what each
|
||||
</span><span id="__span-0-117"><a id="__codelineno-0-117" name="__codelineno-0-117"></a> component is for and how the pieces wire together. Keep it usage-level;
|
||||
</span><span id="__span-0-118"><a id="__codelineno-0-118" name="__codelineno-0-118"></a> exact signatures belong in <span class="sb">`docs/lib/`</span>.
|
||||
</span><span id="__span-0-119"><a id="__codelineno-0-119" name="__codelineno-0-119"></a><span class="k">-</span><span class="w"> </span>Anatomy: numbered sections, one per component (<span class="sb">`## 1. MongoConnectionManager`</span>,
|
||||
</span><span id="__span-0-120"><a id="__codelineno-0-120" name="__codelineno-0-120"></a> <span class="sb">`## 2. BaseDocument`</span>, …), with <span class="sb">`### 8.1`</span>-style sub-numbering for related
|
||||
</span><span id="__span-0-121"><a id="__codelineno-0-121" name="__codelineno-0-121"></a> types under a component (e.g. the cache layer's backend / stats / config /
|
||||
</span><span id="__span-0-122"><a id="__codelineno-0-122" name="__codelineno-0-122"></a> in-memory / redis implementations). Ends with <span class="sb">`## Related`</span>.
|
||||
</span><span id="__span-0-123"><a id="__codelineno-0-123" name="__codelineno-0-123"></a>
|
||||
</span><span id="__span-0-124"><a id="__codelineno-0-124" name="__codelineno-0-124"></a><span class="gu">### 4.4 Use-case page (the most common)</span>
|
||||
</span><span id="__span-0-125"><a id="__codelineno-0-125" name="__codelineno-0-125"></a>
|
||||
</span><span id="__span-0-126"><a id="__codelineno-0-126" name="__codelineno-0-126"></a>Standard anatomy, in this order:
|
||||
</span><span id="__span-0-127"><a id="__codelineno-0-127" name="__codelineno-0-127"></a>
|
||||
</span><span id="__span-0-128"><a id="__codelineno-0-128" name="__codelineno-0-128"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-129"><a id="__codelineno-0-129" name="__codelineno-0-129"></a><span class="sb"># Use Case N: <Human Title></span>
|
||||
</span><span id="__span-0-130"><a id="__codelineno-0-130" name="__codelineno-0-130"></a>
|
||||
</span><span id="__span-0-131"><a id="__codelineno-0-131" name="__codelineno-0-131"></a><span class="sb">**Scenario:** <one sentence: the problem this recipe solves></span>
|
||||
</span><span id="__span-0-132"><a id="__codelineno-0-132" name="__codelineno-0-132"></a>
|
||||
</span><span id="__span-0-133"><a id="__codelineno-0-133" name="__codelineno-0-133"></a><span class="sb">---</span>
|
||||
</span><span id="__span-0-134"><a id="__codelineno-0-134" name="__codelineno-0-134"></a>
|
||||
</span><span id="__span-0-135"><a id="__codelineno-0-135" name="__codelineno-0-135"></a><span class="sb">## 📦 What's New? (table: Component | Description — new API used here)</span>
|
||||
</span><span id="__span-0-136"><a id="__codelineno-0-136" name="__codelineno-0-136"></a><span class="sb">## 🚀 Example (languaged code block, complete runnable-looking snippet)</span>
|
||||
</span><span id="__span-0-137"><a id="__codelineno-0-137" name="__codelineno-0-137"></a><span class="sb">## 💡 Tips (bullets: gotchas, ordering, common mistakes)</span>
|
||||
</span><span id="__span-0-138"><a id="__codelineno-0-138" name="__codelineno-0-138"></a><span class="sb">## Related (§5)</span>
|
||||
</span><span id="__span-0-139"><a id="__codelineno-0-139" name="__codelineno-0-139"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-140"><a id="__codelineno-0-140" name="__codelineno-0-140"></a>
|
||||
</span><span id="__span-0-141"><a id="__codelineno-0-141" name="__codelineno-0-141"></a><span class="gu">### 4.5 Deep-dive / worked-example page</span>
|
||||
</span><span id="__span-0-142"><a id="__codelineno-0-142" name="__codelineno-0-142"></a>
|
||||
</span><span id="__span-0-143"><a id="__codelineno-0-143" name="__codelineno-0-143"></a>For intricate flows (population shapes, cache round-trips), use numbered
|
||||
</span><span id="__span-0-144"><a id="__codelineno-0-144" name="__codelineno-0-144"></a>depth-first sections and comparison tables:
|
||||
</span><span id="__span-0-145"><a id="__codelineno-0-145" name="__codelineno-0-145"></a>
|
||||
</span><span id="__span-0-146"><a id="__codelineno-0-146" name="__codelineno-0-146"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-147"><a id="__codelineno-0-147" name="__codelineno-0-147"></a><span class="sb">## 1. <Write path> (### 1a., ### 1b., … per sub-case)</span>
|
||||
</span><span id="__span-0-148"><a id="__codelineno-0-148" name="__codelineno-0-148"></a><span class="sb">## 2. <Read path></span>
|
||||
</span><span id="__span-0-149"><a id="__codelineno-0-149" name="__codelineno-0-149"></a><span class="sb">## 3. <Round trip / tricky bit></span>
|
||||
</span><span id="__span-0-150"><a id="__codelineno-0-150" name="__codelineno-0-150"></a><span class="sb">## 4. When to use which (comparison table)</span>
|
||||
</span><span id="__span-0-151"><a id="__codelineno-0-151" name="__codelineno-0-151"></a><span class="sb">## Related</span>
|
||||
</span><span id="__span-0-152"><a id="__codelineno-0-152" name="__codelineno-0-152"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-153"><a id="__codelineno-0-153" name="__codelineno-0-153"></a>
|
||||
</span><span id="__span-0-154"><a id="__codelineno-0-154" name="__codelineno-0-154"></a><span class="gu">### 4.6 Best Practices page (`04_*`)</span>
|
||||
</span><span id="__span-0-155"><a id="__codelineno-0-155" name="__codelineno-0-155"></a>
|
||||
</span><span id="__span-0-156"><a id="__codelineno-0-156" name="__codelineno-0-156"></a><span class="k">-</span><span class="w"> </span>Flat themed <span class="sb">`##`</span> sections (e.g. Layering, Lifecycle, Data & Performance,
|
||||
</span><span id="__span-0-157"><a id="__codelineno-0-157" name="__codelineno-0-157"></a> Transactions & Errors, Testing), each a short list of numbered conventions.
|
||||
</span><span id="__span-0-158"><a id="__codelineno-0-158" name="__codelineno-0-158"></a><span class="k">-</span><span class="w"> </span>Pure prose — no large code blocks.
|
||||
</span><span id="__span-0-159"><a id="__codelineno-0-159" name="__codelineno-0-159"></a>
|
||||
</span><span id="__span-0-160"><a id="__codelineno-0-160" name="__codelineno-0-160"></a><span class="gu">### 4.7 Error Handling (`06_*`) / Testing pages</span>
|
||||
</span><span id="__span-0-161"><a id="__codelineno-0-161" name="__codelineno-0-161"></a>
|
||||
</span><span id="__span-0-162"><a id="__codelineno-0-162" name="__codelineno-0-162"></a><span class="k">-</span><span class="w"> </span><span class="gs">**Error Handling:**</span> an exceptions table (<span class="sb">`Exception | Source | Meaning / fix`</span>),
|
||||
</span><span id="__span-0-163"><a id="__codelineno-0-163" name="__codelineno-0-163"></a> a <span class="sb">`> `</span> note on which failures are by design, a <span class="sb">`## 🚀 FastAPI Mapping Example`</span>
|
||||
</span><span id="__span-0-164"><a id="__codelineno-0-164" name="__codelineno-0-164"></a> code block, then <span class="sb">`## 💡 Tips`</span> bullets, then <span class="sb">`## Related`</span>.
|
||||
</span><span id="__span-0-165"><a id="__codelineno-0-165" name="__codelineno-0-165"></a><span class="k">-</span><span class="w"> </span>**Testing example (<span class="sb">`07_*`</span>):** <span class="sb">`## 🚀 Mock-Based Quickstart`</span> (focused code
|
||||
</span><span id="__span-0-166"><a id="__codelineno-0-166" name="__codelineno-0-166"></a> block), <span class="sb">`## 💡 Notes`</span> tip list, <span class="sb">`## Related`</span>.
|
||||
</span><span id="__span-0-167"><a id="__codelineno-0-167" name="__codelineno-0-167"></a>
|
||||
</span><span id="__span-0-168"><a id="__codelineno-0-168" name="__codelineno-0-168"></a>Common to all pages: no frontmatter, <span class="sb">`---`</span> between every major section, and a
|
||||
</span><span id="__span-0-169"><a id="__codelineno-0-169" name="__codelineno-0-169"></a><span class="sb">`## Related`</span> (or variant) footer as the <span class="gs">**last**</span> section.
|
||||
</span><span id="__span-0-170"><a id="__codelineno-0-170" name="__codelineno-0-170"></a>
|
||||
</span><span id="__span-0-171"><a id="__codelineno-0-171" name="__codelineno-0-171"></a>---
|
||||
</span><span id="__span-0-172"><a id="__codelineno-0-172" name="__codelineno-0-172"></a>
|
||||
</span><span id="__span-0-173"><a id="__codelineno-0-173" name="__codelineno-0-173"></a><span class="gu">## 5. The `## Related` footer</span>
|
||||
</span><span id="__span-0-174"><a id="__codelineno-0-174" name="__codelineno-0-174"></a>
|
||||
</span><span id="__span-0-175"><a id="__codelineno-0-175" name="__codelineno-0-175"></a>Every page ends with a cross-link footer. Rules:
|
||||
</span><span id="__span-0-176"><a id="__codelineno-0-176" name="__codelineno-0-176"></a>
|
||||
</span><span id="__span-0-177"><a id="__codelineno-0-177" name="__codelineno-0-177"></a><span class="k">-</span><span class="w"> </span>Always the <span class="gs">**last**</span> section, always preceded by a <span class="sb">`---`</span>.
|
||||
</span><span id="__span-0-178"><a id="__codelineno-0-178" name="__codelineno-0-178"></a><span class="k">-</span><span class="w"> </span>Standard heading: <span class="sb">`## Related`</span> (no emoji).
|
||||
</span><span id="__span-0-179"><a id="__codelineno-0-179" name="__codelineno-0-179"></a><span class="k">-</span><span class="w"> </span>One bullet line; links separated by <span class="sb">` · `</span> (middle dot plus spaces).
|
||||
</span><span id="__span-0-180"><a id="__codelineno-0-180" name="__codelineno-0-180"></a><span class="k">-</span><span class="w"> </span>Link label format: <span class="sb">`[NN – Title](relative_path)`</span> — en-dash, page number, title.
|
||||
</span><span id="__span-0-181"><a id="__codelineno-0-181" name="__codelineno-0-181"></a><span class="k">-</span><span class="w"> </span>Paths are <span class="gs">**relative**</span>: same directory → <span class="sb">`02_custom_repo.md`</span>; parent →
|
||||
</span><span id="__span-0-182"><a id="__codelineno-0-182" name="__codelineno-0-182"></a> <span class="sb">`../01_overview.md`</span>; child → <span class="sb">`03_use_cases/01_basic_crud.md`</span>.
|
||||
</span><span id="__span-0-183"><a id="__codelineno-0-183" name="__codelineno-0-183"></a><span class="k">-</span><span class="w"> </span>Link order follows nav order (each <span class="sb">`Related`</span> points to related next/sibling
|
||||
</span><span id="__span-0-184"><a id="__codelineno-0-184" name="__codelineno-0-184"></a> pages, plus the overview/components anchor).
|
||||
</span><span id="__span-0-185"><a id="__codelineno-0-185" name="__codelineno-0-185"></a>
|
||||
</span><span id="__span-0-186"><a id="__codelineno-0-186" name="__codelineno-0-186"></a>Examples (from mongo-ops):
|
||||
</span><span id="__span-0-187"><a id="__codelineno-0-187" name="__codelineno-0-187"></a>
|
||||
</span><span id="__span-0-188"><a id="__codelineno-0-188" name="__codelineno-0-188"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-189"><a id="__codelineno-0-189" name="__codelineno-0-189"></a><span class="sb">## Related</span>
|
||||
</span><span id="__span-0-190"><a id="__codelineno-0-190" name="__codelineno-0-190"></a><span class="sb">- [02 – Custom repository](02_custom_repo.md) · [04 – Pagination](04_pagination.md) · [Overview](../01_overview.md)</span>
|
||||
</span><span id="__span-0-191"><a id="__codelineno-0-191" name="__codelineno-0-191"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-192"><a id="__codelineno-0-192" name="__codelineno-0-192"></a>
|
||||
</span><span id="__span-0-193"><a id="__codelineno-0-193" name="__codelineno-0-193"></a>Variants:
|
||||
</span><span id="__span-0-194"><a id="__codelineno-0-194" name="__codelineno-0-194"></a>
|
||||
</span><span id="__span-0-195"><a id="__codelineno-0-195" name="__codelineno-0-195"></a><span class="k">-</span><span class="w"> </span><span class="sb">`## ➡️ Read Next`</span> — used on the overview page (linear reading order).
|
||||
</span><span id="__span-0-196"><a id="__codelineno-0-196" name="__codelineno-0-196"></a><span class="k">-</span><span class="w"> </span><span class="sb">`## 🔗 Related Resources`</span> — only on <span class="sb">`index.md`</span>, one bullet per external resource.
|
||||
</span><span id="__span-0-197"><a id="__codelineno-0-197" name="__codelineno-0-197"></a>
|
||||
</span><span id="__span-0-198"><a id="__codelineno-0-198" name="__codelineno-0-198"></a>---
|
||||
</span><span id="__span-0-199"><a id="__codelineno-0-199" name="__codelineno-0-199"></a>
|
||||
</span><span id="__span-0-200"><a id="__codelineno-0-200" name="__codelineno-0-200"></a><span class="gu">## 6. Tone & formatting rules</span>
|
||||
</span><span id="__span-0-201"><a id="__codelineno-0-201" name="__codelineno-0-201"></a>
|
||||
</span><span id="__span-0-202"><a id="__codelineno-0-202" name="__codelineno-0-202"></a><span class="k">-</span><span class="w"> </span><span class="gs">**Written for humans**</span>: short sentences, concrete examples, plain words.
|
||||
</span><span id="__span-0-203"><a id="__codelineno-0-203" name="__codelineno-0-203"></a><span class="k">-</span><span class="w"> </span>Emoji-prefixed H2 headings for recognizable section types
|
||||
</span><span id="__span-0-204"><a id="__codelineno-0-204" name="__codelineno-0-204"></a> (<span class="sb">`📦 What's New?`</span>, <span class="sb">`🚀 Example`</span>, <span class="sb">`💡 Tips`</span>, <span class="sb">`🚀 Key Features`</span>).
|
||||
</span><span id="__span-0-205"><a id="__codelineno-0-205" name="__codelineno-0-205"></a><span class="k">-</span><span class="w"> </span><span class="sb">`---`</span> horizontal rule between every major section.
|
||||
</span><span id="__span-0-206"><a id="__codelineno-0-206" name="__codelineno-0-206"></a><span class="k">-</span><span class="w"> </span>Code blocks always declare a language (```python, ```bash, etc.).
|
||||
</span><span id="__span-0-207"><a id="__codelineno-0-207" name="__codelineno-0-207"></a><span class="k">-</span><span class="w"> </span>Use tables for comparisons and structured decisions; bullets for lists;
|
||||
</span><span id="__span-0-208"><a id="__codelineno-0-208" name="__codelineno-0-208"></a> ASCII diagrams for architecture.
|
||||
</span><span id="__span-0-209"><a id="__codelineno-0-209" name="__codelineno-0-209"></a><span class="k">-</span><span class="w"> </span>Bold key terms inline. Use <span class="sb">`inline code`</span> for symbols/APIs.
|
||||
</span><span id="__span-0-210"><a id="__codelineno-0-210" name="__codelineno-0-210"></a><span class="k">-</span><span class="w"> </span>Keep pages focused: one recipe/purpose per page. If a page balloons past
|
||||
</span><span id="__span-0-211"><a id="__codelineno-0-211" name="__codelineno-0-211"></a> ~10 KB, split it (add a numbered deep-dive page instead).
|
||||
</span><span id="__span-0-212"><a id="__codelineno-0-212" name="__codelineno-0-212"></a><span class="k">-</span><span class="w"> </span>Match tone of existing pages in the repo before writing new ones.
|
||||
</span><span id="__span-0-213"><a id="__codelineno-0-213" name="__codelineno-0-213"></a>
|
||||
</span><span id="__span-0-214"><a id="__codelineno-0-214" name="__codelineno-0-214"></a>---
|
||||
</span><span id="__span-0-215"><a id="__codelineno-0-215" name="__codelineno-0-215"></a>
|
||||
</span><span id="__span-0-216"><a id="__codelineno-0-216" name="__codelineno-0-216"></a><span class="gu">## 7. Build & verify workflow</span>
|
||||
</span><span id="__span-0-217"><a id="__codelineno-0-217" name="__codelineno-0-217"></a>
|
||||
</span><span id="__span-0-218"><a id="__codelineno-0-218" name="__codelineno-0-218"></a>After creating or editing wiki pages:
|
||||
</span><span id="__span-0-219"><a id="__codelineno-0-219" name="__codelineno-0-219"></a>
|
||||
</span><span id="__span-0-220"><a id="__codelineno-0-220" name="__codelineno-0-220"></a><span class="sb">```bash</span>
|
||||
</span><span id="__span-0-221"><a id="__codelineno-0-221" name="__codelineno-0-221"></a><span class="c1"># 1. Build the wiki (from the repo root)</span>
|
||||
</span><span id="__span-0-222"><a id="__codelineno-0-222" name="__codelineno-0-222"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--wiki<span class="w"> </span><span class="c1"># wiki only</span>
|
||||
</span><span id="__span-0-223"><a id="__codelineno-0-223" name="__codelineno-0-223"></a>doc-forge<span class="w"> </span>build<span class="w"> </span>--wiki<span class="w"> </span>--mkdocs<span class="w"> </span>--module<span class="w"> </span><pkg><span class="w"> </span><span class="c1"># wiki + lib together</span>
|
||||
</span><span id="__span-0-224"><a id="__codelineno-0-224" name="__codelineno-0-224"></a>
|
||||
</span><span id="__span-0-225"><a id="__codelineno-0-225" name="__codelineno-0-225"></a><span class="c1"># 2. Preview locally</span>
|
||||
</span><span id="__span-0-226"><a id="__codelineno-0-226" name="__codelineno-0-226"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--wiki
|
||||
</span><span id="__span-0-227"><a id="__codelineno-0-227" name="__codelineno-0-227"></a>
|
||||
</span><span id="__span-0-228"><a id="__codelineno-0-228" name="__codelineno-0-228"></a><span class="c1"># 3. Collect into the hub (run from the docs/ service repo)</span>
|
||||
</span><span id="__span-0-229"><a id="__codelineno-0-229" name="__codelineno-0-229"></a>python<span class="w"> </span>collect.py<span class="w"> </span><span class="c1"># copies site, regenerates index + nginx.conf</span>
|
||||
</span><span id="__span-0-230"><a id="__codelineno-0-230" name="__codelineno-0-230"></a>python<span class="w"> </span>collect.py<span class="w"> </span>--dry-run<span class="w"> </span><span class="c1"># preview without writing</span>
|
||||
</span><span id="__span-0-231"><a id="__codelineno-0-231" name="__codelineno-0-231"></a><span class="sb">```</span>
|
||||
</span><span id="__span-0-232"><a id="__codelineno-0-232" name="__codelineno-0-232"></a>
|
||||
</span><span id="__span-0-233"><a id="__codelineno-0-233" name="__codelineno-0-233"></a>Verification checklist:
|
||||
</span><span id="__span-0-234"><a id="__codelineno-0-234" name="__codelineno-0-234"></a>
|
||||
</span><span id="__span-0-235"><a id="__codelineno-0-235" name="__codelineno-0-235"></a><span class="k">-</span><span class="w"> </span><span class="sb">`doc-forge build --wiki`</span> completes with no warnings about missing files.
|
||||
</span><span id="__span-0-236"><a id="__codelineno-0-236" name="__codelineno-0-236"></a><span class="k">-</span><span class="w"> </span>Every new page is present in <span class="sb">`docs/mkdocs.wiki.yml`</span> <span class="gs">**and**</span> in the index
|
||||
</span><span id="__span-0-237"><a id="__codelineno-0-237" name="__codelineno-0-237"></a> Documentation Structure table.
|
||||
</span><span id="__span-0-238"><a id="__codelineno-0-238" name="__codelineno-0-238"></a><span class="k">-</span><span class="w"> </span>Every page ends with a <span class="sb">`## Related`</span> block and no dead links (paths resolve).
|
||||
</span><span id="__span-0-239"><a id="__codelineno-0-239" name="__codelineno-0-239"></a><span class="k">-</span><span class="w"> </span>After <span class="sb">`collect.py`</span>: the hub card links to both <span class="sb">`/wiki/`</span> and <span class="sb">`/lib/`</span> and the
|
||||
</span><span id="__span-0-240"><a id="__codelineno-0-240" name="__codelineno-0-240"></a> pages render (spot-check with the served site).
|
||||
</span><span id="__span-0-241"><a id="__codelineno-0-241" name="__codelineno-0-241"></a><span class="k">-</span><span class="w"> </span>If code/docstrings changed (no change when wiki-only), run the repo gates:
|
||||
</span><span id="__span-0-242"><a id="__codelineno-0-242" name="__codelineno-0-242"></a> <span class="sb">`black`</span>, <span class="sb">`ruff`</span>, <span class="sb">`mypy`</span>, <span class="sb">`pytest`</span>.
|
||||
</span><span id="__span-0-243"><a id="__codelineno-0-243" name="__codelineno-0-243"></a>
|
||||
</span><span id="__span-0-244"><a id="__codelineno-0-244" name="__codelineno-0-244"></a>---
|
||||
</span><span id="__span-0-245"><a id="__codelineno-0-245" name="__codelineno-0-245"></a>
|
||||
</span><span id="__span-0-246"><a id="__codelineno-0-246" name="__codelineno-0-246"></a><span class="gu">## 8. Before/after checklist</span>
|
||||
</span><span id="__span-0-247"><a id="__codelineno-0-247" name="__codelineno-0-247"></a>
|
||||
</span><span id="__span-0-248"><a id="__codelineno-0-248" name="__codelineno-0-248"></a><span class="gs">**Before creating a page:**</span>
|
||||
</span><span id="__span-0-249"><a id="__codelineno-0-249" name="__codelineno-0-249"></a>
|
||||
</span><span id="__span-0-250"><a id="__codelineno-0-250" name="__codelineno-0-250"></a><span class="k">- [ ]</span> Confirm it is genuinely wiki material (how-to) and not API contract.
|
||||
</span><span id="__span-0-251"><a id="__codelineno-0-251" name="__codelineno-0-251"></a><span class="k">- [ ]</span> Find the right filename (<span class="sb">`NN_snake_case.md`</span>) and directory for its theme.
|
||||
</span><span id="__span-0-252"><a id="__codelineno-0-252" name="__codelineno-0-252"></a><span class="k">- [ ]</span> Outline the sections per §4 anatomy that fits the content.
|
||||
</span><span id="__span-0-253"><a id="__codelineno-0-253" name="__codelineno-0-253"></a>
|
||||
</span><span id="__span-0-254"><a id="__codelineno-0-254" name="__codelineno-0-254"></a><span class="gs">**After creating/editing a page:**</span>
|
||||
</span><span id="__span-0-255"><a id="__codelineno-0-255" name="__codelineno-0-255"></a>
|
||||
</span><span id="__span-0-256"><a id="__codelineno-0-256" name="__codelineno-0-256"></a><span class="k">- [ ]</span> Page wired into <span class="sb">`docs/mkdocs.wiki.yml`</span> nav (themed subgroup if needed).
|
||||
</span><span id="__span-0-257"><a id="__codelineno-0-257" name="__codelineno-0-257"></a><span class="k">- [ ]</span> <span class="sb">`index.md`</span> Documentation Structure table updated.
|
||||
</span><span id="__span-0-258"><a id="__codelineno-0-258" name="__codelineno-0-258"></a><span class="k">- [ ]</span> <span class="sb">`## Related`</span> footer present, relative links, nav order.
|
||||
</span><span id="__span-0-259"><a id="__codelineno-0-259" name="__codelineno-0-259"></a><span class="k">- [ ]</span> <span class="sb">`---`</span> separators consistent; no frontmatter; emoji headings where apt.
|
||||
</span><span id="__span-0-260"><a id="__codelineno-0-260" name="__codelineno-0-260"></a><span class="k">- [ ]</span> Build passes; collect run; hub shows <span class="sb">`/wiki/`</span> + <span class="sb">`/lib/`</span> links.
|
||||
</span><span id="__span-0-261"><a id="__codelineno-0-261" name="__codelineno-0-261"></a><span class="k">- [ ]</span> No orphaned files, no dead links.
|
||||
</span></code></pre></div></td></tr></table></div></li>
|
||||
</ul>
|
||||
<hr />
|
||||
<p>© Aetoskia Internal</p>
|
||||
|
||||
Reference in New Issue
Block a user