Wiki: Docs, Tutorials #124
Comments
|
How about using GitHub's wiki system and moving all documentation to it? I'd be willing to write about the parts that I have a decent grasp on. |
|
I was thinking about that last night! A GitHub wiki seems like the way to go. It's clone-able, so I don't feel tied in. As for you contributing, that sounds great! Thanks. I think I'd like to write the opening sections myself, but you're welcome to add on. |
|
@lokesh-krishna I would be happy to have you create and write sections, I take back what I said about starting them. I've been tied up with code (#61) and also day-to-day life. Let me know if you can! I've created the Wiki, with a dummy first page. That way you can open PRs to add to it. |
|
Hey, |
|
Here is what I have so far: Amfora WIki |
|
Thanks! I'm happy to add that as it is and then make my own changes, but I'll come online this afternoon (EST) and we can talk. |
|
Your page was added with some small changes, and the sections it contained were removed from the README. |
|
Added sections on URL-handlers and proxying (which includes the few proxies that I know of). |
|
Thanks! Unfortunately I think this is just starting to look like a big README. I want to split this up into different pages to make it more readable, and to allow a user to focus on the areas they want. But I'm not sure exactly what the pages would be. Any ideas? I'll think about it more as well. Once we figure that out, I can add these new sections. Other things:
|
I like the Polybar wiki's organization a lot and think their categorization with a home page and then separate pages for compiling, configuration and theming would be a good fit for Amfora too.
Right, I did add yours as a remote but forgot to sync. If you settle upon an organization scheme then would it be too much to ask if I could be a collaborator for just the wiki? GitHub has made things needlessly unwieldy otherwise.
I'm pretty confused about this myself. I based this choice upon Drew's Kineto which is described as a HTTP to Gemini proxy. It lets you serve a Gemini capsule over HTTP. So I figured these proxies that make a HTTP site available on Gemini would be Gemini to X proxies. |
|
The polybar wiki organization is not super clear to me, but seems decent. For Amfora I think having a general configuration page is good, but I don't want to end up putting everything in there, like URL handlers and proxies. Maybe just at the top pages that require configuration just link back to config page? Like polybar does here. As for specific pages, I think if you look at the opening comment in this issue and go off that that'd be good. Each top-level checkbox should have it's own page. Maybe with a different name though, like instead of it being named
You've been invited as a collaborator. Once you accept, you should be able to edit the wiki yourself. Please let me know here when you add/edit things, but you're welcome to go ahead and do it.
I realize it's more complicated than I thought, because both portals and proxies are biderectional. Portals take HTTP requests from the user and make Gemini requests, and then translate the Gemini responses into HTTP. Proxies are vice-versa. I would still consider proxies to be X-to-Gemini, since most of the flow of content is the response, which starts out as protocol X, and then is turned into Gemini. |
Yup, that sounds good. I'll go with that then :)
Thank you so, so much! I'm honoured! I definitely mean for everything to be reviewed by you first. Can we do branches on the wiki? That way nothing would get on the main branch until you approved it.
This is all I needed. I just kept getting confused. |
Thanks, good idea. You should be able to, let me know if you have any issues. Let me know when you've reorganized and pushed the URL-handlers and proxying sections, and I'll take a look. Thanks! |
|
I've pushed my changes to the |
|
Thank you, merged. You can look at the branch history and the master branch history for changes I made. Some things for the future:
|
|
It seems to me like there's now an overlap between the documentation in the config file and in the Wiki. The recently added pages are nice, but it seems like they mostly just copy what's said in the config file. But I think they're good for bringing attention to the feature, and for providing extra info, like links to proxies. But I don't want to maintain docs in two separate places. Thoughts on how to reconcile this? |
|
I think all projects have this redundancy though it's usually in the form of an online wiki and an offline man page. I don't think Amfora is complex enough (yet) to need a man page and I love that you can just copy over the default config file and know everything you need to configure Amfora. I wouldn't want the information to disappear from the default config file. Maybe we could add more information to the wiki? I am limited by my knowledge but if you were willing to share any notes or make the additions yourself then the wiki could address more involved workflows, additional context and edge cases. An example of this would be the page on subscription giving a brief overview of all supported formats with their advantages and shortcomings. The config file meanwhile would just provide the bare minimum. Eventually though I think we might need a man page, judging by all that's in store and I would love to be a part of it. EDIT: Having gone through #142, I can definitely see the need for a man page arising soon. We would need documentation for all that the infobar is capable of but the default config would grow too cluttered if all of it was added there. I strongly believe that all programs should ship with comprehensive offline documentation though so...
Default config file has the bare minimum, comprehensive man page, wiki which at least matches the man page in covering features and configuration with maybe additional context and links to relevant projects (such as proxies). |
Agreed. It would be simpler for me to just maintain everything in the wiki and link to it in the config file, but I think having it all there is much nicer for users.
This makes sense to me. I was more wondering about how write the info that's already in the config. Like so far it's been rewritten into prose sentences, but would it be better to just paste the config in there? Like so: # Allows setting the commands to run for various URL schemes.
# E.g. to open FTP URLs with FileZilla set the following key:
# ftp = 'filezilla'
# You can set any scheme to "off" or "" to disable handling it, or
# just leave the key unset.
#
# DO NOT use this for setting the HTTP command.
# Use the http setting in the "a-general" section above.
#
# NOTE: These settings are overrided by the ones in the proxies section.
# Note the use of single quotes, so that backslashes will not be escaped.
# This is a special key that defines the handler for all URL schemes for which
# no handler is defined.
other = 'off'And then additional info can be written afterwards in sentences.
I'm not a huge fan of man pages, and I'm not sure if it's really needed here. Why can't the instructions for the info bar just be added to the config?
I was thinking config file with relevant info and short explanation, and wiki with more info, context, example setups, etc. |
This is good. Would be make it easier to update both too if they share the same base. We could just drop the comments and use code blocks for the actual config stuff?
I just like that they provide an entirely offline yet entirely complete source of documentation. However, if you mean for the config file to still cover everything then I think there's no need for one.
Let's go ahead with this then? |
That's what I was thinking, yeah.
Basically I was just thinking to copy the minimal info in the config file into the wiki as a TOML code block, and then write extra info on the wiki outside of that. Is that what you understood?
Yep, I like just having that single offline source for info.
Sounds good! Unrelated, but I'm planning to mirror the wiki on my capsule with a script that uses |
So all the info in the config file that is in the form of comments would remain as comments within the TOML code block? I was thinking the comments could be moved out of the code block but leaving it in would sure make it even easier to keep both updated. |
|
Yep, that's what I was thinking. It also makes it obvious to the user what information is in the config and what is not. I will update the wiki to do this with existing pages. |
|
@lokesh-krishna I've added a full page on the Subscriptions feature, would be happy to have you take a look, and maybe try out the feature too! It's in master. Let me know if you need a binary. |
|
That's a comprehensive implementation with a comprehensive wiki page to go along with it :) EDIT: |
|
Glad you like both the code and page! Thanks for the fixes. And yes, I'm planning on linking the wiki page. Just want to get the wiki running on Gemini first, so I can link to both versions. |
|
The wiki is now on Gemini! And it's in the new tab page, as of 507c6e8.
|
|
I will keep this open as more sections will need to be added over time, but I'm removing it from the v1.7.0 milestone as all the docs I wanted for that release are done. |
|
Wiki is done for v1.8.0, but this page will need to be updated to remove the "not released yet!" notice at the top. |
|
Things to add for v1.9.0 that don't have issues:
|
|
Todo for v1.10.0 release
|
The wiki has started!
Amfora is growing, and its feature-set is becoming larger and less obvious when casually browsing. I feel that the README is also becoming a bit cluttered. Some documentation or tutorials on specific features should be created to resolve this, and then linked in the README.
Documentation Topics
[url-handlers]config section[[mediatype-handlers]]config section(s) (Mediatype handlers #121)Readme changes
<details>and<summary>Other
contrib/The text was updated successfully, but these errors were encountered: