[web][doc] Change the typedoc output #976
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
And move there typedocsOptions present in tsconfig.json file.
From `jsdoc` to `typedoc` because it is actually the pacakge/command used for generating the documentation.
And document `UsersClient` defined at src/client/users to avoid a warning genrated by typedoc: > [warning] UsersClient, defined in ./src/client/users.js, is referenced > by client.InstallerClient.users but not included in the documentation.
And fix issues while importing some type defintions from clients because a wrong path. > Error: Expected a symbol for node with kind Identifier at > /home/dgdavid/development/agama/web/src/context/l10n.jsx:27 > Error: Expected a symbol for node with kind Identifier at > /home/dgdavid/development/agama/web/src/context/product.jsx:27 Imports for @typedef in these files were using `src/clients/` instead of `src/client`.
Also fixes a bad written link and some imports for @typedef which were either, using a wrong path or missing a namespace. Just for future references, find below errors related with these wrong imports, > Error: Expected a symbol for node with kind Identifier at... > AssertionError [ERR_ASSERTION]: Missing symbol when converting import type node...
To avoid having a log of "default" references. Visit below links to know more, * https://github.com/felipecrs/typedoc-plugin-rename-defaults#readme * TypeStrong/typedoc#1521
For a future integration with static site generators like Docusaurus or
Vitepress, this commit applies the necessary typedoc configuration and
plugins for a more reasonable output structure. Of course, it can (when
not must) be improved, but it's a good starting point for testing.
In short, this commit
* Adjusts some typedoc options like sort, navigation, and others.
* Uses the typedoc-plugin-external-module-map in ordert to avoid
adding the "@module Whatever" at the beginning of each file
manually.
* Uses typedoc-plugin-merge-modules to group docs of the same module
and category. Since it renames the default exports it makes
typedoc-plugin-rename-defaults obsolete.
* Separates client and component documentation processing tasks since
their organizational structure differs slightly.
* Creates a new task for running these two.
Despite not been included in this commit, typedoc-plugin-markdwon will
be needed for mentioned integration.
To know more,
* https://typedoc.org/options/organization/
* https://github.com/asgerjensen/typedoc-plugin-external-module-map
* https://github.com/krisztianb/typedoc-plugin-merge-modules
* https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/typedoc-plugin-markdown
* https://docusaurus.io/
* https://vitepress.dev/
To keep the autogenerated content accessible from doc/index.html.
dgdavid
changed the title
dgdavid
changed the title
Some core/Page documentation was sent with mistakes in #925. This commit fixes the mistakes, although it does not introduce big improvements because it is already out of the scope of the PR in which is sent.
dgdavid
added a commit
that referenced
this pull request
Jan 20, 2024
Few weeks ago, the documentation output was reworked a bit to be ready for a near future in which all the project documentation could be "managed" by a static site generator. These adjustments implied a few changes that were not reflected in the README file. [1] #976
dgdavid
added a commit
that referenced
this pull request
Jan 20, 2024
Few weeks ago, the documentation output was reworked a bit to be ready for a near future in which all the project documentation could be "managed" by a static site generator. These adjustments implied a few changes that were not reflected in the README file. [1] #976
dgdavid
added a commit
that referenced
this pull request
Jan 20, 2024
A few weeks ago, the [documentation output was reworked a bit](#976) to be ready for a near future in which all the project documentation could be "managed" by a static site generator. These adjustments implied a few changes that were not reflected in the README file.
Closed
Merged
imobachgs
added a commit
that referenced
this pull request
May 17, 2024
Prepare for releasing Agama 8. It includes the following pull requests: * #884 * #886 * #914 * #918 * #956 * #957 * #958 * #959 * #960 * #961 * #962 * #963 * #964 * #965 * #966 * #969 * #970 * #976 * #977 * #978 * #979 * #980 * #981 * #983 * #984 * #985 * #986 * #988 * #991 * #992 * #995 * #996 * #997 * #999 * #1003 * #1004 * #1006 * #1007 * #1008 * #1009 * #1010 * #1011 * #1012 * #1014 * #1015 * #1016 * #1017 * #1020 * #1022 * #1023 * #1024 * #1025 * #1027 * #1028 * #1029 * #1030 * #1031 * #1032 * #1033 * #1034 * #1035 * #1036 * #1038 * #1039 * #1041 * #1042 * #1043 * #1045 * #1046 * #1047 * #1048 * #1052 * #1054 * #1056 * #1057 * #1060 * #1061 * #1062 * #1063 * #1064 * #1066 * #1067 * #1068 * #1069 * #1071 * #1072 * #1073 * #1074 * #1075 * #1079 * #1080 * #1081 * #1082 * #1085 * #1086 * #1087 * #1088 * #1089 * #1090 * #1091 * #1092 * #1093 * #1094 * #1095 * #1096 * #1097 * #1098 * #1099 * #1100 * #1102 * #1103 * #1104 * #1105 * #1106 * #1109 * #1110 * #1111 * #1112 * #1114 * #1116 * #1117 * #1118 * #1119 * #1120 * #1121 * #1122 * #1123 * #1125 * #1126 * #1127 * #1128 * #1129 * #1130 * #1131 * #1132 * #1133 * #1134 * #1135 * #1136 * #1138 * #1139 * #1140 * #1141 * #1142 * #1143 * #1144 * #1145 * #1146 * #1147 * #1148 * #1149 * #1151 * #1152 * #1153 * #1154 * #1155 * #1156 * #1157 * #1158 * #1160 * #1161 * #1162 * #1163 * #1164 * #1165 * #1166 * #1167 * #1168 * #1169 * #1170 * #1171 * #1172 * #1173 * #1174 * #1175 * #1177 * #1178 * #1180 * #1181 * #1182 * #1183 * #1184 * #1185 * #1187 * #1188 * #1189 * #1190 * #1191 * #1192 * #1193 * #1194 * #1195 * #1196 * #1198 * #1199 * #1200 * #1201 * #1203 * #1204 * #1205 * #1206 * #1207 * #1208 * #1209 * #1210 * #1211 * #1212 * #1213 * #1214 * #1215 * #1216 * #1217 * #1219 * #1220 * #1221 * #1222 * #1223 * #1224 * #1225 * #1226 * #1227 * #1229
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
In general, the Agama documentation start aging bad. It's either, disperse in a bunch of files, outdated, incomplete, or sometimes even wrong.
At the time of writing, using a static site generator like Docusaurus or Vitepress look as good bet to start fixing these problems by putting all the Agama information accessible in a kind of website without too much effort.
In that context, with these tools in mind, this PR can be seen a starting point for having a better output of autogenerated documentation.
Next steps must include reviewing all the written documentation for fixing and improving at the same time that
@category,@internal, and other Typedoc tags are used correctly for an even better output.Follow the commits to dig into details ;)
Click to show/hide a not much helpful screenshots
The index, 🙈
^^^ Note the typo in Fronted
The generated doc