It looks like I have been running an unintended version of Python
from GitHub Actions. In Linux/Mac I used `python3`, and in Windows
I used `py`. It appears that I should be executing `python` in
all 3 operating systems.
This is an experiment to see if I can get everyone on the same page.
The JavaScript functions were appearing in unsorted
order in the markdown documentation.
The `jsdoc2md` tool does not have an option for sorting them.
So I wrote a new script `sort_js_functions.py` that post-
processes the markdown to sort the functions.
It turns out that "sed" does not work on Mac OS,
and I wasn't even trying to patch the version
numbers on Windows. I decided to write a Python
program for this task, so it will work identically
on all 3 operating systems.
Added a new file generate/version.txt that contains
the current Astronomy Engine version number.
Now when I run the build/test process, the version
number is patched in all the places it needs to
be changed to keep all the packages and documentation
up to date.
This means when I want to change the Astronomy Engine
version number, I just need to edit version.txt, then
execute the generate/run script.
Generate astronomy.py directly in the package directory.
I realized it doesn't make sense to generate it in the
parent directory and then copy it; just generate it where
it will end up anyway.
Updated documentation so people know they can just do
pip install astronomy-engine
to install Astronomy Engine in their Python project.
Removed the GitHub Actions status badge because it is redundant with
the checkmark/X indicator.
Now that private symbols are no longer exported, I had to
fix a couple of places where the unit tests still accessed them.
The pip package was broken!
I violated ancient software development wisdom:
"If you haven't tested it, it doesn't work."
It is now working in:
https://pypi.org/project/astronomy-engine/2.0.15/
Version 2.0.15 of Astronomy Engine for Python (pip)
and Node.js (npm) add support for the new SiderealTime
function. This was previously an internal function,
but now it is exposed for outside callers.
The program 'realpath' does not come installed on Mac OS.
This caused the bash script 'makedoc' to fail on Mac.
The only place I used realpath was to convert relative
paths to absolute paths for filenames passed to
check_internal_links.py.
It turns out Python has a standard function os.path.realpath()
that does the same thing, so I moved the logic into the
Python script itself. Thus makedoc no longer needs the
realpath program, and the Python function will work on
all platforms.
There is a general lesson here: in the future I will
consider moving more of my scripting logic into Python.
It has proven to be more portable than a mixture
of bash scripts and Windows batch files.
When building Astronomy Engine for publication,
I was disabling generation of C documentation by default,
because I used to have issues getting deterministic output
in the CI tests (GitHub Actions). Now I have reason to believe
it will work reliably, so I am turning on C docs generation
by default.
If this fails the CI test, I will have to make the CI test
explicitly disable this step until I figure out how to fix it.
Otherwise (and preferably) the CI test will ensure that the
published C documentation is always up to date, and will fail
the build if there are any issues generating the docs.
I also had forgotten to enable installing dependencies for
my custom tool `hydrogen` in the Windows build. I added a fix
for that.
For now, I'm keeping beta/unfinished website and tutorial stuff
outside the master branch to reduce confusion for newcomers.
It will stay in the `tutorials` branch for any ongoing development.
If we finish it and make it ready for public use, then I will
bring it back into `master`.
Updated the `makedoc` script to gracefully skip steps
involving tutorials or website if they are absent.
Also, we were not installing packages needed for `hydrogen`
to generate C documentation. This broke document generation
on freshly-cloned repos.
I'm trying to make it easier for first-time visitors to
this project to find the source code and documentation
to get started quickly. Moved directories that are only
used by contributors (mostly myself) out of the root
and into the 'generate' directory where they are less
distracting.
Worked around an issue where the npm package google-closure-compiler
assumes the current architecture is Intel x64.
This caused a broken install on the Raspberry Pi.
Detect non-Intel architecture and fall back to installing
only the Java version of the Closure compiler.
Automatically update the front page README.md to include the current
byte size of astronomy.browser.min.js. Fail the build process if
this file ever grows to 100000 bytes or larger.
Ported the ObserverVector function to C#, but it is not tested yet.
While doing that, I realized I needed a way to document newly public
constants DEG2RAD, RAD2DEG, and KM_PER_AU. This led to work
on the 'csdown' project that converts C# XML documentation
into Markdown format.
Then I realized a lot of code would be more elegant if
AstroVector had operator overloads for addition, subtraction,
and dot products.
This in turn required these operators to know which time value
to store in the AstroVector, which led to realizing that I
was sloppy in a lot of places and passed in null times.
So this whole commit contains a variety of unrelated topics,
which is something I don't usually do, but it felt
justified here while I'm in a refactoring mood.
Also moved the NPM commands to the package.json
so the makedoc scripts execute them in a central place.
Installed a jsdoc theme to improve the html output.
The npm dependencies required are now
installed locally inside the generate folder.
Cleaned up the Astronomy object closure for TS
and kept it for the Browser bundle.
We will have some usage examples in the website.
Improved the type checking by using tsc --strict.
Nothing substatial changed in the generated JavaScript, and no
actual bugs were found, but I removed a lot of loose/sloppy
type signatures. This should make mistakes less likely
in the JavaScript code going forward.
The goal is to provide both TypeScript and JavaScript to developers.
Will also provide a type definition file once I figure that out.
This is just the first pass through the code.
It builds and passes all the unit tests, with some minor changes
to the generated README.md.
Windows does not support relative links in Git by default.
This broke the first-time experience for Windows users.
From now on I will maintain copies of the astronomy.js
and astronomy.py in the demo folders, so that the demos
will work on Windows immediately after cloning the repo.
Currently I ignore any errors when checking the C# documentation,
because there are broken links for the rotation functions I
haven't started adding yet. I will turn that error check back on
once I finish those functions.
I will need to use reflection into the astronomy.dll assembly,
along with the generated astronomy.xml, to generate Markdown
documentation. This is the start of that project.
I was going to write a Python program to parse the
xml file generated by the C# compiler.
The problem is it does not contain enough information
about types, as explained here:
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features
"The XML file does not provide full information about the type and members
(for example, it does not contain any type information).
To get full information about a type or member, the documentation file
must be used together with reflection on the actual type or member."
So that means I will end up writing the documentation generator in C#
and using reflection along with the XML file to generate Markdown.
Decided to move call to makedoc script from run script.
It was confusing that it was hidden inside unit_test_js,
especially because it invokes the code generator for
all supported languages.
Once again, existing tools are too complicated and don't do what I want.
It's actually easier to create my own tool for this special purpose.
I also want the documentation to be similar in style to the other languages.
Got makedoc.bat to generate compatible documentation with
Linux makedoc script. Started to document all the stuff
developers have to install to work on this project.
It turns out it simplifies things to merge all the doxygen xml
files into a single all.xml file, then process that. That way
I can find all the struct definitions too.
I don't know if this is going to do what I want, but I'm
hoping I can customize the Markdown output generated by moxygen
to be useful for a simple C library like this. It appears to be
customized for a class-oriented C++ program.
The version of doxygen supported in Travis CI appears to be
too old to work with moxygen. This is just not worth the hassle.
I will generate documentation locally, and I will document to
any prospective contributors how to do so also.
