Documentation Improvements

[mspublic]

G3 is a great project! The documentation on how to fully setup everything end to end unfortunately is a bit lacking.

I am creating this issue to track improvements in documentation.

I will definitely help on the English side/work with the team to translate as best as possible/submit PRs for them. Also I would like to help submit new example configs as well.

@zh-jq - would you like me to create new issues for all areas that are needing documentation or should we keep that just under this main issue?

Example:

1. How would I use g3proxy to do forward proxying with SSL inspection? (Needing to use g3fcgen etc).

2. How do I configure a “frontend” with g3fcgen?

These as just examples. @zh-jq if it’s easier to quickly right your docs in Chinese I can use tools to translate - but will need to have you review for accuracy.

Thanks again for all your work!!

[zh-jq]

The documentation on how to fully setup everything end to end unfortunately is a bit lacking.

Yes, this need to be improved.

I am creating this issue to track improvements in documentation.

It's fine and let's keep it open. This would be a long-term issue.

I will definitely help on the English side/work with the team to translate as best as possible/submit PRs for them. Also I would like to help submit new example configs as well.

Thanks

@zh-jq - would you like me to create new issues for all areas that are needing documentation or should we keep that just under this main issue?

For big parts I'm OK with both the way. For small parts you can just submit PRs directly.

How would I use g3proxy to do forward proxying with SSL inspection? (Needing to use g3fcgen etc).

I have updated the user guide this week and you can check that again.

How do I configure a “frontend” with g3fcgen?

I will add a README for g3fcgen next week.

@zh-jq if it’s easier to quickly right your docs in Chinese I can use tools to translate - but will need to have you review for accuracy.

Thanks again.

I'm not good at writing even in Chinese. I will try my best to do that. Let me know if you have suggestions on the organization of the docs, or have confusion on the missing parts, or want to see more comments for some specific code.

[mspublic]

Along the lines of documentation - I am working on adding more debugging statements in the code/libraries. I am currently using log::debug. For example in g3-icap-client these are the type of comments (see below). Is this format OK with you?

impl IcapServiceClient {
    pub fn new(config: Arc<IcapServiceConfig>) -> Self {
        debug!("Creating new IcapServiceClient");
        let (cmd_sender, cmd_receiver) = flume::unbounded();

[zh-jq]

I'm OK with this. But only essential ones should be added.

[GlenDC]

Related to this ticket. There's already a great document called dev-setup.md. Thank you for that, very helpful.
What I am however still missing as a contributor is a set of instructions that you as the maintainer of g3 run for Q&A. E.g. tests, and w/e.

I know that with a language like rust the cargo tooling has it mostly bundled already, but still there are usually a set of flags and options to pass to it, especially in a more complex workspace as this. Would be nice to have these common commands you run yourself for g3 be documented somewhere, or perhaps even have a justfile or makefile with such common targets. As right now I am working with raw cargo commands myself while modifying g3 code, but it's not hard to imagine that I might forget some bits and bobs.

[zh-jq]

The cargo commands in github CI currently only do build/clippy/unit test. Previously I have also added coverage tests in scripts/coverage dir, which is a bit outdated. I will rework the integration tests later to cover more features and also make it easier to do coverage test and pgo/bolt build.

[GlenDC]

If you want I can as a first step already push a Makefile or Justfile (up to you what you prefer) with those CI cmds available for developers? Could be an easy first step, or do you want to think about it a bit and move forward with a step later?

[zh-jq]

If you want I can as a first step already push a Makefile or Justfile (up to you what you prefer) with those CI cmds available for developers? Could be an easy first step, or do you want to think about it a bit and move forward with a step later?

You can go ahead. I'm still not sure about how that should be.