Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[web][doc] Change the typedoc output #976

Merged
merged 17 commits into from
Jan 9, 2024
Merged

[web][doc] Change the typedoc output #976

merged 17 commits into from
Jan 9, 2024

Conversation

dgdavid
Copy link
Contributor

@dgdavid dgdavid commented Jan 2, 2024

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, 🙈

Before After
Screen Shot 2024-01-08 at 15 47 11 Screen Shot 2024-01-08 at 15 47 04

^^^ Note the typo in Fronted

The generated doc

Before After
Screen Shot 2024-01-08 at 15 46 04 Screen Shot 2024-01-08 at 15 44 16
Note that only src/client doc was generated. Which actually could make sense, but let's generate the components docs too by now to help us to catch mistakes there. We can evaluate in the future if we want to link it or not Screen Shot 2024-01-08 at 15 44 46

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...
@coveralls
Copy link

coveralls commented Jan 2, 2024

Coverage Status

coverage: 74.935%. remained the same
when pulling 8fa1935 on fix-doc
into b8b9e64 on master.

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 dgdavid changed the title [WIP] Fix web documentation Fix web documentation Jan 8, 2024
@dgdavid dgdavid changed the title Fix web documentation [web][doc] Change the output of auto-generated doc Jan 8, 2024
@dgdavid dgdavid marked this pull request as ready for review January 8, 2024 15:54
@dgdavid dgdavid changed the title [web][doc] Change the output of auto-generated doc [web][doc] Change the typedoc output Jan 8, 2024
@dgdavid dgdavid requested a review from imobachgs January 8, 2024 16:41
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.
Copy link
Contributor

@joseivanlopez joseivanlopez left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@dgdavid dgdavid merged commit 2d79033 into master Jan 9, 2024
2 checks passed
@dgdavid dgdavid deleted the fix-doc branch January 9, 2024 13:32
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.
@imobachgs imobachgs mentioned this pull request Feb 12, 2024
@imobachgs imobachgs mentioned this pull request May 17, 2024
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
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants