But that's not what you should do at all. You are juggling

1: obsolete script API docs that are not user friendly or helpful outside the specific function they serve
2: An attempt at a sphinx deployment that is unfinished and abandoned but it was a good attempt that was half reverted.
3: A wiki that uses markdown where the rest of the project uses RST

Users should be guided to a single location for docs and you should have a uniform strategy for it across the project.

The most sensible option I see based on my experience here is that you just use the Github hub wiki, bring this up to date with all info needed and purge the pages sites.

I posted a long reply to @Elliria as to why I don't think this will work for us. Of note is that GitHub is permissioned, so only authorized users can modify it. That's where the "official" documentation should be (and is except for the API docs.) Our wiki is currently not permissioned and this encourages users to contribute examples, etc. whenever they want to without administrative overhead and delays. So far, we have only had one "incident" (an accidental deletion) in well over ten years, so security/integrity hasn't been a problem.

if we can get the automatiic API documentation to reside on GitHub, that would be great.

Iirc on the branch with the docs changes, if you run something like tox -e docs it should re-generate the files. Should be documented, but probably only on that branch's readme or contributors atm

So, if a change is made to something in the docs in the development branch and I ran tox -e docs from that branch, the remote docs at https://autokey.github.io/autokey/ would be updated and then contain that change?

Also, where does the script (or whatever is doing it) that generates the documentation live, @BlueDrink9?

If this works, we can leave them as is, @josephj11.

Not sure on develop - I think the github.io docs explicitly point to a folder on a branch, can't recall which. But otherwise, building the docs then pushing the changed files should do it, yes.

The script is just a subcommand written in setup.cfg

@josephj11 checked the GitHub Pages settings yesterday and the old documentation points to the /doc/scripting folder (on master, I believe - I don't think it specified that) and from what I'm gathering about how this works, the current documentation generates the /autokey folder on github.io, but that folder is nowhere to be seen. It's all very mysterious.

Your link looks like it will also do the trick. It says it doesn't delete anything, but it will no longer be visible to users.

Not sure what you're referring to (unless I already answered it elsewhere). I bet all we have to to is change develop to none and the errors will go away. Doing that will probably take the new API docs with it. It would be useful to take some sort of static copy of that first and save it somewhere else in the repo. It needs to have live inks in it like it does now to be useful.

Once we figure out how to generate it manually, we can do so on demand to create an updated version until such a time as we have another automatic method that actually works. We don't have to delete any of it, so if someone can fix it later, it will still be there configured as it is now. We won't have to figure it out from scratch.

What I'm wondering about is how to disable the test in the source code so that that particular test doesn't run at all. Otherwise, I suppose it will continue to fail. I'm not familiar enough with the code to know what will need to change.

I don't understand most of it yet, but perhaps with enough research, it can be figured out. Thanks for the links.

I don't think so. The last time I got an update to the Terms of Service was on July 09, 2017.

Setting that parameter to None seems like it will work. It stopped the page from being generated in my dummy repository without causing any errors. That's a very basic repository, though. Oh, and changing the settings back the way they were brings the page back, so you can always change your mind on this later if you like.

It looks like you found the Gitter conversation and it's amazing what Sam has done. Now we just need to figure out how to implement it.

As for the state of the old documentation, it's currently in three places, none of which are identical. Aside from one typo that got fixed, all the other differences between them are for naming conventions, and this is the current lay of the land:

• AutoKey 0.94.1 and earlier use the legacy documentation that's served by GitHub Pages from here.
• AutoKey 0.95.0 through AutoKey 0.95.10 should use the documentation in the develop and/or master branch that's not being served online. These releases can use the same legacy documentation that's served by GitHub Pages from here for some things, but not all.
• AutoKey 0.96.0-beta-1 and later use the new documentation that Sam created.

I ithink we can safely ignore the legacy documentation, but since people routinely use old versions of Linux on old hardware, we should probably not delete it any time soon.

0.95.x defintely incluuded things that are not in 0.94.x, so a version of that documentation needs to exist and be preserved online, but it should include a notice that it's not the latest version if we can figure out how to do that. I don't think we can or should do anything about regenerating it.

There should be one static version of it. Since, AFAIK, it can't be regenerated (broken old software...), ideally, we should be able to delete any files on GitHub that are only useful for regenerating it. IDK any of the details of this or the best way to preserve this documentation and keep iti available.

Sam's new documetation is great and I'm looking forward to getting it integrated into production when we figure out how to do that. It does have one "bug" because it is still titled as 0.95.10, but I'm sure that's a small fix and it occured because that's the version that existed when it was implemented.

I'm looking into ways that we can use to convert the legacy documentation into a document that can be downloaded so that we can get it out of the repository, but it uses frames, which complicates matter when it comes to converting it into a single, flat file.

I still use AutoKey 0.95.10, because that's what came with Kubuntu 22.04 LTS, so I'm one of those folks.

I'm not sure on the logistics of working with the new documentation and how we would edit it, back it up, or convert it to a flat file in the future if major changes are made to it, but hopefully we'll learn all of that.

The 0.95.10 thing won't be a problem once we know where it's getting it from. I just searched through the files in master, develop, and the wiki and got these results for a search for 0.95.10:

In master:

CHANGELOG.rst:Version 0.95.10 <2019-12-16>
debian/changelog:autokey (0.95.10-0) bionic; urgency=medium
lib/autokey/configmanager/version_upgrading.py:    logger.info("Version update: Unhiding sidecar dotfiles for versions > 0.95.10")

In develop:

CHANGELOG.rst:Version 0.95.10 <2019-12-16>
debian/changelog:autokey (0.95.10-0) bionic; urgency=medium
lib/autokey/configmanager/version_upgrading.py:    logger.info("Version update: Unhiding sidecar dotfiles for versions > 0.95.10")

In the wiki:

Advanced-Scripts.md:# This script works in AutoKey 0.95.10.
Home.md:Below is a screenshot of the main window (in version 0.95.10) currently editing a Script:
Installing.md:    VERSION="0.95.10"    # substitute with the version you downloaded
Installing.md:    $ pip3 install --user https://github.com/autokey/autokey/archive/v0.95.10.zip
Troubleshooting.md:Due to the way AutoKey monitors the keyboard, it still sees the remapped Caps-lock key as "Caps-lock", even though other applications see the remapped key. So AutoKey can not automatically detect this situation. Support for remapped Caps-lock keys was added in version 0.95.10.
Troubleshooting.md:So to fix this, make sure you run at least version 0.95.10. Then go to the AutoKey applications settings and check the option "Disable handling of the Capslock key", then restart AutoKey (Use `File` → `Quit`, then start AutoKey again). 

I'm not knowledgeable about web development, but what happens if you open one of those pages in a browser and select the save as option or use a wget of some sort? You're saving the resulting web page, not whatever was used to generate it, but shouldn't that be OK?

I'm not clear as to what you were looking for when searching for 0.95.10.

The results illustrate why I don't like changing the master. I'm pretty sure that unhidden sidecar files was added in 0.96.0, but here it is, at least in a message, in 0.95.10. That's the sort of uncertainty I don't want to have to deal with.

Getting each of the legacy pages won't be a problem (wget works great for that). Interconnecting them in a logical way in a flat file and editing out the parts that don't belong in the flat file would be very time-consuming).

When I searched for 0.95.10, it was an effort to find where the Sphinx documentation is getting it from so that we can change it in the source.

I am following your conversations and awed by the depth of knowledge required to go through the maze built built by other contributors. While this is way above my pay grade, nevertheless I enjoy this thoroughly. Thank you.

This means so much to me, @ineuw. Just knowing you're there and that you're following along is a great comfort. Also, I have a feeling you'll spot something I missed. This is above my pay-grade as well, which is what's making it so messy. I'm pretty much just hoping that we stumble into the solutions quite accidentally for some of the puzzles we're coming across. I suppose if we wander around enough, it could happen.

It should be separate, but I'll address it here anyway.

This is a big topic and I think I have addressed it elsewhere, but I can't look now.

The basics:
The technical tools for this exsit and there appear to be several good ones. That's not really an issue.

AutoKey does not exist as an organization, let alone have a defined taxation status or jurisdiction. There is no mechanism for receiving any funds, accounting for them, or distributing them. At a minimum, we woud need to form and run a DAO or a corporation of some sort. Probably lots of research and work.

Periodically, we do get offers of donations, but since none have ever been accepted, we have no idea of how much money might be involved. These things typically work well for large projects with a lot of small donations or when a benfactor decides to make a larger investment. In both cases, the donors might expect certain results for their donations. This could be an issue.

Individuals could create their own funding apparatus using something like Patreon. That would work fine techncally, but raises issues of who deserves to get paid and how much. This would be random from the project's point of view and might lead to some people feeling that the distribution of funds was unfair. Again, there has to be enough money involved to make it all worth bothering with and we have no idea if that would be the case.

I have literally thousands of hours invested in AutoKey and would love to get some income from it, but I don't want to jeopardize the project and I never expected to get paid for any of it.

My take on it is that the amount of money it would take to attract the kind of developers who are capable of understanding and fixing all of the code and then actually compensating them for the time it would take to do so would be staggering and I doubt our project could could get enough people to pony up that kind of cash.

I've seen mention, somewhere in all of our discussions here or on outside platforms, of bounties, which would be much smaller investments usually made by individuals for very specific wishes, as @josephj11 pointed out. Even though those tend to be smaller and focused on a single aspect of the code, they can rapidly grow and get rather messy quite quickly simply because of the way their tentacles are intertwined in the rest of the code and those need to be unraveled to get the job done, which can make them simply not worth doing, at least by the kind of folks who are in it for the money.

I'd guess that all of us who have put our fingers into the pie so far have done so out of either a love and/or need for the program. We probably just need to keep trying to attract that kind of contributor, with high hopes that we can bring in some incredibly knowledgeable ones.

Yep. You can also grab the source files from its repository here.

I tested it in my dummy repository and nothing got deleted and I was able to reinstate the pages by turning it back on again. You won't need to do that, though. GitHub Pages is doing absolutely nothing for us, because we don't have anything in the directory it wants to serve pages from, so changing its setting won't change our documentation. You can just disable it and leave it that way until or unless we need it for the new documentation that @sebastiansam55 is doing the code for.

@sebastiansam55 You just gave us the reason why your approach is the right one. I see no reason to update the old docs, but it will be easy to add a link to them in the new doc. (IDK how to do that because it's generated, but hopefully, you do.)

@Elliria The old docs have been static for a very long time (almost a decade?) and that hasn't caused any problems that I'm aware of, so it should be safe to leave them alone. I do agree that we should keep them available for a few years because lots of people use old Linux distros.

You can have versioned sphinx documentation but that's something someone else can tackle should they choose to. imo it's not worth the overhead as we should be telling users to update to the latest version as major version updates include lots of bug fixes, impractical to support more than the most current version imo

Versions? We don't need no stinking versions! (paraphrased Bogart quote)

I doubt that anyone will notice and not like the updated, searchable interface.

Should be fine, but a link to the old version would cover all bases.

@Elliria Given that Sam is our only "adavanced" developer, I'm not if favor of him working on anything that's nice but not necessary.

This was a question about a configuration setting.

@Elliria Sorry. I must have missed that.

Now that the two documentation URLs are "flipped", all the links were wrong. I fixed the obvious ones in README, Documentation and API Examples. There are probably more that need fixing, so keep an eye out for errant links.

BTW I added Sam to the Contributors Team, so he has maintenance permissions now and can do merges, etc. I also added the github.io repo to the Contributors team, so Sam can work on that as well. Telling you FYI and so somebody other than me knows what was done in case I'm not around.

Thank you so very much for taking care of this documentation issue, @sebastiansam55. The documentation was in dire straits. You're a true hero. ❤❤❤

Yep. Me, too. I just corrected the errant not that snuck into my post. Thanks for testing.