Documentation and HOW-TOs #33

hw commented 2019年03月08日 07:18:52 +01:00

To get new users started, to facilitate workflow and clarify issues for experienced users, documentation and HOWTOs seem helpful.

We might start them in a dedicated repo, potentially publish them as static pages?

To get new users started, to facilitate workflow and clarify issues for experienced users, documentation and HOWTOs seem helpful. We might start them in a dedicated repo, potentially publish them as static pages?

hjacobs commented 2019年03月23日 12:00:06 +01:00

We could also use the excellent and community-driven readthedocs.io service for documentation. I think his might be more valuable than re-creating another documentation hosting site which needs to be maintained (even if it is just a script triggering the rebuild+publish of static pages).

We could also use the excellent and community-driven [readthedocs.io service](https://readthedocs.org/) for documentation. I think his might be more valuable than re-creating another documentation hosting site which needs to be maintained (even if it is just a script triggering the rebuild+publish of static pages).

hw commented 2019年03月23日 17:22:13 +01:00

:) we need content!

:) we need content!

hjacobs commented 2019年03月23日 18:22:24 +01:00

Let's start with some simple "getting started" guide explaining how to register, upload SSH key, and create a repo?

If you want I can set up a Sphinx or Mkdocs repo (depends on personal preference) with publishing to readthedocs.io and some first content. Simple example of what I'm talking about: https://pykube.readthedocs.io (source repo is https://github.com/hjacobs/pykube/tree/master/docs)

Let's start with some simple "getting started" guide explaining how to register, upload SSH key, and create a repo? If you want I can set up a Sphinx or Mkdocs repo (depends on personal preference) with publishing to readthedocs.io and some first content. Simple example of what I'm talking about: https://pykube.readthedocs.io (source repo is https://github.com/hjacobs/pykube/tree/master/docs)

hw commented 2019年03月23日 21:41:33 +01:00

Good idea! Even a set of simple markdown files in a repo would be a good start, those we can then format into any suitable format.

(This would have the advantage that editors can use Gitea's builtin WYSIWYG editor for markdown files, and Sphinx can read those too, if the appropriate plugin is installed. Also gitea's wiki can directly import/export pages as md).

Good idea! Even a set of simple markdown files in a repo would be a good start, those we can then format into any suitable format. (This would have the advantage that editors can use Gitea's builtin WYSIWYG editor for markdown files, and Sphinx can read those too, if the appropriate plugin is installed. Also gitea's wiki can directly import/export pages as md).

buhtz commented 2019年05月28日 11:20:20 +02:00

I would need someting like that.
I need to know how to connect my "local git" to my codeberg-repo.

Also some workflows would be nice

• password-less access to the codeberg-repo (it is about SSH, keys, etc)
• "synchronize" local and codeberg-repo (pull and fetch?)
• hanlding conflicts while "synchronize" etc

I would need someting like that. I need to know how to connect my "local git" to my codeberg-repo. Also some workflows would be nice - password-less access to the codeberg-repo (it is about SSH, keys, etc) - "synchronize" local and codeberg-repo (pull and fetch?) - hanlding conflicts while "synchronize" etc

buhtz commented 2019年06月04日 17:00:48 +02:00

My recommendations as a more detailed table of content for the wiwk

• Use git and Codeberg with username and password (clone & push)
• Setup Codeberg to use it password-less with git
  • generate and upload a key
    • Passphrase or not? what are the consequences for the workflow!?
    • separate key for each client/machine or one key for all?
    • what is this ssh-keyagent about?
  • clone & push
• Setup git (remote, master, etc) to be used with Codeberg
• Setup KeePassXC to be used with git on Codeberg

My recommendations as a more detailed __table of content__ for the wiwk - Use git and Codeberg with username and password (clone & push) - Setup Codeberg to use it password-less with git - generate and upload a key - Passphrase or not? what are the consequences for the workflow!? - separate key for each client/machine or one key for all? - what is this ssh-keyagent about? - clone & push - Setup git (remote, master, etc) to be used with Codeberg - Setup KeePassXC to be used with git on Codeberg

ashimokawa commented 2019年06月04日 17:47:50 +02:00

@buhtz
You can go ahead and just start, if you like 👍
The wiki is also a git repository internally, we can fix/move/rename whatever we want later anyway (even if seemingly not possible by editing online)

an ssh-agent will unlock your keys (by entering the passphrase once) and will then be able to use that key without a passphrase. Therefore I think it is better to always generate a key with passphrase. I am a bit old-school, and I think Desktop environments nowadays have fancy gui popups, but what I do here is:

$ ssh-agent bash # this starts a new bash that acts as ssh-agent
$ ssh-add # will ask for passphrase

Now as long as that bash runs, I am able to push and pull without passwords.

@buhtz You can go ahead and just start, if you like :+1: The wiki is also a git repository internally, we can fix/move/rename whatever we want later anyway (even if seemingly not possible by editing online) an ssh-agent will unlock your keys (by entering the passphrase once) and will then be able to use that key without a passphrase. Therefore I think it is better to always generate a key with passphrase. I am a bit old-school, and I think Desktop environments nowadays have fancy gui popups, but what I do here is: ``` $ ssh-agent bash # this starts a new bash that acts as ssh-agent $ ssh-add # will ask for passphrase ``` Now as long as that bash runs, I am able to push and pull without passwords.

6543 commented 2020年12月03日 00:43:34 +01:00

https://docs.codeberg.org/ is nice and works

https://docs.codeberg.org/ is nice and works