-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathRBD-Notes.txt
264 lines (236 loc) · 16.2 KB
/
RBD-Notes.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
Alpyca Device - Sample/Template Alpaca (Rotator device)
-------------------------------------------------------
28-Dec-2022 Starting to make notes. I got quite a ways along with this. Now I want to set up
to do the docs ion Sphinx. I don't plan to extract info from docstrings just to keep the
code from being cluttered. I have put comments into the source in plain # form.
Now to set up for making Sphinx docs. What a process. Although I made the Alpyca docs,
and a start on the ASCOM Master docs, using Sphinx and rinohtype, it was so full of crazy
tinkering and problem hunting I just wanted to forget it all Hance these notes so I can
save myself from a fresh round of (repeat) frustrations.
So starting with the RBD-Notes from the Alpyca project and using VSCode for RST writing:
* (21-Jul-2022) Install the Sphinx-related packages into the .venv get all of the sphinx and
rinoh pieces into the .venv because the reStructuredText extension depends on the esbonio
language server, and that is actually real-time rendering the document at design time!
This led to several hours of installing shit.
==== AHHHH ====
Look at the docs/source/conf.py and those things are in the extensions. REDO THE VENV... AGAIN!!!
* This time I created the venv python -m venv .venv and restarted VSCode. It found the .venv OK. Then I followed
the prompts to install docutils and esbonio, RESTART, then again via "Problems" to install rinohtype RESTART
then again to get sphinx_rtd_theme, which BACK-REVVED DOCUTILS to 0.17.1. Damn. These things are in the Sphinx
conf.py file, which was getting confused with mine before I renamed it.
* ==== HOORAY ==== The reStructruredText extension is working!! It found the junk .rst files I put there as place
holders. Now I need to clean up the Sphinx conf.py ... done.
* Moved over to the RPi. I installed Sphinx, the rsStructuredText VSCode plugin popped up installs for docutils,
and esbonio. I restarted, esbonio can't install the rinoh.frontend.sphinx plugin. I installed rinohtype
pip install rinohtype. No luck even after starting VSCode. So I went to https://github.com/brechtm/rinohtype
and found how to install the latest version via pip/GitHub:
https://github.com/brechtm/rinohtype
This installed markdown-it-py-2.1.0 mdit-py-plugins-0.3.3 mdurl-0.1.2 myst-parser-0.18.1 pyyaml-6.0
rinohtype-0.5.5, and removed rinohtype-0.5.3. No luck. wtf. It's not showing on the pip list either.
HOW WEIRD - Now same deal with sphinx_rtd_theme. So I used the Pip Manager to install them. Well now
rinoh stuff shows in pip manager but not in the pip list????? Now Esbonio/pip succeeds but without
* Making HTML docs!!! I wanted to disable the "hyperlink not referenced" errors from rstcheck, but
trying to follow the directions in the manual I added a setting "--ignore-errors REGEX_STRING" but no
luck. So I want back into settings restructuredtext: Linters: Disabled-linters, and disabled rstcheck.
This caused restructuedtext to start asking to load the restructuredtext_lint package, so I installed
that with pipmanager. It is there now.
* DAMN - Now it is using rst-lint, a brain damaged linter that doesn't know some of the directives
like .. only:: So I want back and disabled that one. GRRRRR Now it wants doc8. So I installed that with pip.
HOORAY!!! It is using doc8. This one has ways of controlling the errors and other stuff. See the
VSCode settings restructuredtext.linter.doc8.extraArgs and remove the rstcheck shit. Right below
in the JSON are the disabling items. I must hve done this before (dump rstcheck and rst-lint).
Anyway doc8 is finding my errors in real time.
03-Jan-2023
-----------
* It is OK to make Sphinx docs on the command line if you deactivate the .venv. That's enough
for now till I decide to get into another wrestling match with version conflicts. TRhe older
versions of packages in the global site-packages all seems to work so DON'T TOUCH IT!!!
* === OH!! ALong the lower left of the VSCode status bar, there is a selector for the Sphinx path!!
I never saw this. It was set to use <docutils> but I changed it to use Sphinx with the conf.py
info. Maybe this will remove some of the inscrutable linting stuff.
One of the effects is to add this wo the workspace level settings:
"esbonio.sphinx.confDir": "${workspaceFolder}/docs/source",
This makes me realize that esbonio can benefit from not guessing, and that this is project-specific,
so now I will commit the alpaca-device.code-workspace to the Git repo, along with the thunder-tests
in order to create a portable dev environment.
* Shit, esbonio is now building into docs/source/_build instead of docs/build. This is with the
.venv deactivated. Is there no end to the surprises and side effects?
+ OK, I have now set up the workspace settings so that esbonio builds into
docs/build/_esbonio/ (doctrees and html), and also Sphinx builds into docs/build
(doctrees and html).
"settings": {
"esbonio.sphinx.confDir": "${workspaceFolder}/docs/source",
"esbonio.sphinx.buildDir": "${workspaceFolder}/docs/build/_esbonio"
}
This makes it easy to .gitignore the esbonio output while keeping it separate from the
actual Sphinx final build output for HTML and rinoh/PDF.
16-Jan-2023
-----------
**************************************
** RESET ON VENV VS GLOBAL ON LINUX **
**************************************
* Create new .venv2, then activate in VSCode. NOTE: The only way to get this to sork with the 'select interpreter' on the status bar is to first pick "AlpycaDevice ~/Documents" then in the new Select Interpreter list select the one you want!
+ Install only falcon and toml, update pip and setuptools.
+ DEVELOP WITH .venv2
+ When documenting, in VSCode select the global environment which has all of the shit. THIS WORKS including linting.
+ Simply deactivating in the terminal DOES NOT WORK if VSCode is set to .venv2, since the linters etc. aren't instaled.
================
== CONCLUSION ==
================
* Coding and testing, have VSCode set for .venv2
* Working on docs, have VSCode set for Global site-packages
-- Update Sphinx and linters --
1. PipMgr Update Sphinx to 6.1.3 - Build OK after removing contents of /build folder (old pickled). esbonio OK 6.1.3
2. PipMgr Update Doc8 to 1.1.1
3. PipMgr update rstcheck -> 6.1.1 and rstcheck-core to 1.0.3
4. PipMgr Update sphinx-autodoc-typehints to 1.21.1, sphinx jinja-compat to 0.2.0, sphinx-rtd-theme to 1.1.1
sphinx-tabs to 3.4.1, sphinx-toolbox to 3.3.0 -->> SHIT SPHINX IS NOW BACK AT 4.5.0 ?!?!?!?!?
5. PipMgr Refresh, Update Sphinx to 6.1.3, and again sphinx-autodoc-typehints to 1.21.1, DOCS OK.
6. Update zope.interface to 5.5.2 (fron dev version)
17-Jan-2023
-----------
* Renamed the repo AlpycaDevice. Renamed root folders on Linux and Windows, adjusted the virtual environment activation scripts
* Removed the messy .venv on Linux and renamed .venv2 from yesterday to .venv. Develop with .venv, do docs with global.
* Rename repo and project root directories to AlpycaDevice.
+ Rename repo on GitHub
+ Rename root on Windows, fix up .venv/Scripts/activate scripts (multiple).
== Painless on Windows, the .venv activates as before and GitHub still OK ==
* At GitHub, the old repo path /alpyca-device still works but does a redirect to the real /AlpycaDevice.
I decided to update the git remote info on Linux and Windows to point to the
new git remote. Under VSCode Remote menu, remove origin. Then add remote from
Git, my AlpycaDevice one. This was a snap on Linux, Clicking the Publish To
just fixed it up. On Windows I had to
git branch --set-upstream-to=origin/master master
to get it to work again. All OK in the end.
* Well one remaining issue - On Windows, in the .venv (the original), the sphinx-build.exe has embedded in it
the old path alpyca-device. WTF? So renaming the project root to AlpycaDevice
caused this. How did that venv path get into Scripts\sphinx-build.exe? Guess:
when installed into .venv. Well this is even worse. pip doesn't even work.
ooks like the end of the .venv on Windows too. Forget this venv too!!!
* WINDOWS == Same usage of .venv for dev, global for doc. Killed the old messy .venv, created a new one
with just pip, setuptools, falcon, and toml. If you select that interpreter the doc tools will croak.
That's fine. Don't open a .rst doc when running on the .venv.
* In global, many packages updated using pip-manager in VSCode. Specifically the sphinx-related ones
were updated. Sphinx is limited to 5.3.0 owing to the Python on this system being limited to 3.7.
After this esbonioneeded to be updated too. Done.
18-Jan-2022
-----------
* Holy smokes! The Rewrap plugin (by stkb) is the BOMB! Alt-q and it is smart enough to wrap
a lot of the structures use by reST. I love it. Just write, and when the paragraph is finished
or edited chopped up, alt-q :-) :-)
* Ideas for writing:
Three types of exceptions here:
1. Errors in the HTTP request itself -> 400 or 404
2. Device operational errors RunTimeError -> Alpaca DeviceException and detailed message with -> 200 -> logged also
3. Python uncaught exception in the Falcon responder class -> 500 -> Logged also
4. Python uncaught exception in the app outside Falcon -> Logged and possible app death.
28-May-2023
-----------
* On the W10 system, running from global environment, the RST extension is failing to start esbonio for a space in the
command line. The author doesn't give a shit per the GitHub traffic. NOW WHAT? GOD ALMIGHTY THIS STUFF IS SOOOOOO
FRAGILE. I seem to recall that I needed to revert to 189.1.0..... I did it and now it works. DAMN! I opened the
Extension page and the "Update to 189.3.0 dropdown has an option "Ignore Updates". I did it. That "cured" the
problem. You should see the traffic on GitHub for the RestructuredText extension. The author says "well no
one uses Windows anyway"" yet it worked fine 2 releases previous.
####################################################################
### DO NOT UPDATE THE RESTRUCTURED TEXT EXTENSION BEYOND 189.1.0 ###
####################################################################
01-Jun-2023
-----------
* RST previewer isn't working right for my CHANGES.rst. Yeah, the CHANGES.rst file did not get compiled.
Apparently, the preview feature depends on the RST file being compiled by esbonio. Running it does not compile
CHANGES.rst because it is outside the docs folder. It is not part of the docs but there for viewing on GitHub
at the rood of the folder tree. No preview on this.
* I keep getting this cryptic message while editing RST docs with a squiggle yellow at the end of the editor.
RuntimeWarning: 'doc8.main' found in sys.modules after import of package 'doc8', but prior to execution
of 'doc8.main'; this may result in unpredictable behaviour
Great. Try to find any info on this ha ha ha. I'm pretty sure doc8 is an RST linter? This should be fun....
* Reminder frm a horrible wrestling match on another project where the PDF construction in Sphinx (rinohtype)
dies for any Sphinx runs. This turned out to be the importlib-metadata packate (Python) which nededs to stay
at 4.1.4. Maybe later but I don't have time to look at this. Apparently as I recall there wa sa breaking API
change with V6 that sacorched Sphinx and/or Rinoh.
##########################################################################
### DO NOT ALLOW PYTHON PKG IMPORTLIB-METADATA TO UPDATE BEYOND 4.11.4 ###
##########################################################################
02-Jun-2023
-----------
* After suffering with inscrutable gigantic errors in the Esbonio output window, yellow squiggles in
random places seemingly at a given line regardless of the content at that location, I disabled
the doc8 and rst-lint linters, leaving rstcheck. I vaguely recall a wrestling match with rstcheck
last year but I'm sick of this **** so bye-bye. The random balloon popups and output-filling casdading
errors are now gone. Thank goodness.
* To do the preceding I had to edit the VSCode JSON settings. Now the CTRL-K + CTRL-R for open
RST preview to the side and CTRL-SHFT-R to open RST preview in a tab have been covered. They are still
in the Keyboard Commands list, but CTRL-K + CTRL-R opens keyboard-shortcuts-windows.pdf in the PDF
reader, and CTRL-SHFT-R opens the Thunder Client pane on the left. I found 'thunder' in the mappings
and removed that one, and 'shortcuts' revealed help keboard shortcuts reference and I removed that.
I'm sure I'm gonna need to do this again.
15-Feb-2024
-----------
* ThunderClient stopped working because it wanted a subscription to store the activity and collections
along with the workspace. I subscribed but the ****ing activation process requirees email on your
development machine (long story!). I really wanted the collections I made to test AlpycaDevice SDK
The files in the ThunderTests workspace folder are where they are, but Thunder can no longer use
them without $35/year. In thunder settings you have to shut off the Workspace Data setting.
Reading their docs, I found that by moving the collection JSON files to
%APPDATA%\Code\User\globalStorage\rangav.vscode-thunder-client
I can again use Thunder. This is not an issue with the Thunder on the old Win7 system which
is 2.4.3. Well I reverted to 2.4.3 on the Windows 10 system and it can't find the stuff in the
workspace so to hell with it.
16-Feb-2024
-----------
* I had a few messages with Thunder and they had to make a change. After doing so, I was able to
successfully register ThunderClient on the main W10 system so now I can keep the ThunderClient
requests within the AlpycaDevice workspace once again. This is good.
17-Feb-2024
-----------
* Back to this s**t
RuntimeWarning: 'doc8.main' found in sys.modules after import of package 'doc8',
but prior to execution of 'doc8.main'; this may result in unpredictable behaviour"
This time, in User settings (W10 system), reStructuredText, Disabled Linters, add doc8
along with rst-check, leaving rstcheck as the linter. Good enough.
05-Mar-2024
-----------
* Using the most recent (March 2) JSON from the OmniSimulator, the templates were rebuilt.
CoverCalibrator now has the formerly missing members.
* Added OperationCancelledException
* Docs for the 0.7.0 built.
13-Sep-2024
-----------
* Decided no 0.8 but to go with 1.0 in the platform7 branch
* Add separate enum definitions in files under templates/enum, then merge the enum blocks into the
templates during generation. Required a changes to the device boilerplate app.py to avoid trying
to make a responder for the enum classes.
* Start on final 1.0 docs - Migration Guide. Not going to make PDF for this due to many links for
opening externals in separate tabs, which don't work in PDF.
14-Sep-2024
-----------
* Complete Migration Guide, style enhancements, fix a few cross-references etc.
* Change copyrights to cover thru 2024
* Update tests to use latest ConformU Version 3.1.0 (Build 31181.cb32ac3), include latest logs.
08-Oct-2024
-----------
* Merge platform 76 branch onto master.
* Re-do HTML docs and publish in regular place /public_html/ascomsite/alpycadevice and dump temporary alpycadevice7 folder
* As usual PDF fails. Put in the Rinoh fix Desc_Sig_Space see conf.py at the top. SUCCEEDED!!!!!
04-Jan-2025
-----------
* See GitHub Issue #15 https://github.com/ASCOMInitiative/AlpycaDevice/issues/15 ... the OmniSimulators 0.4.1 has 'ID' in the Switch method parameters. ConformU 4.1.0 tests OmniSim 0.4.1 successfully. So which is it???
07-Jan-2025
-----------
* It's 'Id' as in the Master Interfaces. Peter fixed the OmniSim and gave me a new JSON input for the templates AlpacaDeviceAPI_v2_plat7-0.4.1.json
05-Feb-2025
-----------
* 1.0.1 Regenerated templates for the Id thing and for Fix #16 for property Connected on_put() and a typo. 1.0.1.
16-Feb-2025
-----------
* Fix ClientID and ClientTransactionID in shr.py per GitHub #17. Release 1.0.2
20-Feb-2025
-----------
* ALERT: USE THE SYSTEMWIDE P11 INTERPRETER NOT VIRTUAL ENVIRONMENT FOR DOCUMENT LINTING AND BUILDING
- It appears that the RST is syntax colored byt not linted. No esbonio, etc.
* Back to review the rotator device for threading and timers, and FRAGILITY ALERT there are errors in conf.py
- No module named 'rinoh' [Ln 10, Col1]
- Import "rinoh.frontend.rst" could not be resolved [Ln 10, Col 6]
-> from rinoh.frontend.rst import DocutilsInlineNode
- Nonetheless the PDF Builds!! ** NEVER MIND **