Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: describe Makefile targets & add reST primer #1776

Merged
merged 25 commits into from Dec 28, 2019

Conversation

@return42
Copy link
Collaborator

return42 commented Dec 18, 2019

With the aim to simplify development cycles, started with PR #1756 a Makefile
based boilerplate was added. This patch adds the missing developer
documentation.

For a preview use my mirror (don't bookmark):

return42 added 4 commits Dec 18, 2019
With the aim to simplify development cycles, started with PR #1756 a Makefile
based boilerplate was added.  This patch adds the missing developer
documentation.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
preview: https://return42.github.io/searx/dev/reST.html

includes:

- :class: rst-example // admonitions with (rendered) reST markup example
- extlinks to docutils

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
@return42 return42 changed the title doc: describe Makefile targets doc: describe Makefile targets & add reST primer Dec 20, 2019
return42 added 2 commits Dec 20, 2019
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
@dalf

This comment has been minimized.

Copy link
Collaborator

dalf commented Dec 20, 2019

This graphviz may help to understand the architecture (If this is the right one).

digraph G {

  node [style=filled,shape=box, fontname="Arial" fontsize="8"];
  edge [fontname="Arial" fontsize="8"];
  browser [label="Browser",shape=Mdiamond];
  rp [label="Reverse Proxy", href="url to configure reverse proxy"];
  filtron [label="Filtron", href="https://github.com/asciimoo/filtron"];
  morty [label="Morty", href="https://github.com/asciimoo/morty"];
  static [label="Static files", href="url to configure static files"];
  uwsgi [label="uwsgi", href="url to configure uwsgi"]
  searx1 [label="Searx #1"];
  searx2 [label="Searx #2"];
  searx3 [label="Searx #3"];
  searx4 [label="Searx #4"];

  browser -> rp [label="HTTPS"]
  subgraph cluster_searx {
      label = "Searx instance" fontname="Arial" fontsize="12";
      { rank=same; static rp };
      rp -> morty [label="optional\nimages and HTML pages proxy"];
      rp -> static [label="optional\nThe reverse proxy serves directly the static files"];
      rp -> filtron [label="HTTP"];
      filtron -> uwsgi [label="HTTP"]
      uwsgi -> searx1;
      uwsgi -> searx2;
      uwsgi -> searx3;
      uwsgi -> searx4;
  }

}
@return42

This comment has been minimized.

Copy link
Collaborator Author

return42 commented Dec 20, 2019

This graphviz may help to understand the architecture (If this is the right one).

Good Point, I will add it to the docs .. is there any origin for, or is the link already the origin?

return42 added 3 commits Dec 20, 2019
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
@dalf

This comment has been minimized.

Copy link
Collaborator

dalf commented Dec 21, 2019

I'm not sure to understand what you mean by "origin".

About the links between the components:

@return42

This comment has been minimized.

Copy link
Collaborator Author

return42 commented Dec 22, 2019

I'm not sure to understand what you mean by "origin".

If you copied this image from another place it's origin is the "other place" and we have to ask about the licenses. But I guess it was made by yourself (and the link is the only origin)?

BTW: I tested the your DOT markup, but I got problems when it renders the selected font Arial .. which is proprietary .. and not installed on most (build) linux servers. To me it seems, that the fallback font has different sizes and the calculated boxes sizes (SVG) are smaller then the lines of text (overwrite effects). Sorry for the bad description .. I haven't had time to dig deeper into digraph, and fonts at built time and fonts which are used in the viewer on client site, when the SVG is rendered and an explicit font (Arial) is selected in the SVG (xml) but not installed on the system.

@dalf

This comment has been minimized.

Copy link
Collaborator

dalf commented Dec 22, 2019

  • Yes I made it myself.
  • Liberation Sans or DejaVu Sans are okay.

Licenses:

return42 added 3 commits Dec 22, 2019
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Herein we add some hints and suggestions about typical architectures of
searx infrastructures.  We start with a contribution from @dalf

- #1776 (comment)

thanks @dalf !!

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
BTW: minor profread of reST.rst

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
@return42

This comment has been minimized.

Copy link
Collaborator Author

return42 commented Dec 22, 2019

@dalf: I added your DOT graph (see aa3b026). I got best result with fontsize leafed unset and font family 'Sans'. If needed, we can change this later, when PR is merge upstream.

preview (don't bookmark): https://return42.github.io/searx/admin/architecture.html

@dalf

This comment has been minimized.

Copy link
Collaborator

dalf commented Dec 22, 2019

I'm not sure this is the right place. In my opinion, most of the wiki should be moved to the reST documentation:

About the reverse proxy configuration / installation:

A way to deal with the reverse proxy configurations (if possible):

  • define some variables (from this or somewhere else)
  • generate the Apache, nginx, caddy, haproxy configurations using some templates, useful especially for the HTTP headers (Content-Security-Policy header etc...).

It would avoid different versions of the configuration.

Perhaps, each reverse proxy should have it's own page in the reST documentation.

Anyway, most probably this PR must be merged in the master branch before dealing with the wiki.

@return42

This comment has been minimized.

Copy link
Collaborator Author

return42 commented Dec 22, 2019

I'm not sure this is the right place. In my opinion, most of the wiki should be moved to the reST documentation

It was one of my intentions, good to hear that other think same.

Anyway, most probably this PR must be merged in the master branch before dealing with the wiki.

@dalf do you like to open a issue with a copy of your comment above / mark it as 'doc'' and we an pick up it after this PR is merged upstream.

@return42

This comment has been minimized.

Copy link
Collaborator Author

return42 commented Dec 22, 2019

Is there anyone who has time to review / merge this PR upstream? (cant merge my own PR)

BTW: we need to update gh-pages, this can be done with:

make clean gh-pages

Should I do? .. or who maintains gh-pages branch?

@dalf dalf mentioned this pull request Dec 22, 2019
2 of 8 tasks complete
return42 added 2 commits Dec 22, 2019
- Plugins configured at built time (defaults)

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
@return42 return42 requested a review from kvch Dec 22, 2019
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
@return42 return42 requested a review from asciimoo Dec 23, 2019
@return42 return42 requested review from dalf and Pofilo Dec 23, 2019
requirements-dev.txt Show resolved Hide resolved
return42 added 5 commits Dec 23, 2019
preview (don't bookmark):

  https://return42.github.io/searx/dev/contribution_guide.html#code

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
preview (don't bookmark):

  https://return42.github.io/searx/dev/contribution_guide.html#code

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
See issue #1785:

  idea: in the doc, provide installation instructions with one tab per
  distrubution

preview (don't bookmark):

  https://return42.github.io/searx/dev/reST.html#tabbed-views

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
@dalf

This comment has been minimized.

Copy link
Collaborator

dalf commented Dec 26, 2019

Some notes:

@return42

This comment has been minimized.

Copy link
Collaborator Author

return42 commented Dec 26, 2019

so Sphinx loads mathjax from the Cloudflare CDN

ups, I haven't been aware of. I Have to look for a solution that does not load content from CDNs!

The zoom effect on grouped tab makes the reading difficult.

I use it for a long time, but I also doubt since that time that this is the solution i wanted.

I looking for a better solution, do you have any preferences?

And: thanks for your deep inspection!

@dalf

This comment has been minimized.

Copy link
Collaborator

dalf commented Dec 26, 2019

I looking for a better solution, do you have any preferences?

I prefer without the animation effect, so removing the lines 75, 76 and 82 would be enough :
https://github.com/asciimoo/searx/pull/1776/files#diff-7e4e00712fa761cac6e56c7591bffb0cR75-R76

return42 added 3 commits Dec 28, 2019
- Literal blocks
- Unicode substitution
- Horizontal list
- Math equations

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
@return42

This comment has been minimized.

Copy link
Collaborator Author

return42 commented Dec 28, 2019

so Sphinx loads mathjax from the Cloudflare CDN

this is fixed with d1892b2 / the math are rendered as images

The zoom effect on grouped tab makes the reading difficult.

this is fixed with b91e07b the rst-example is rendered slightly more discreet

preview (don't bookmark): https://return42.github.io/searx/admin/buildhosts.html

@dalf, do you have time to make a review of this PR on github?

@return42 return42 requested a review from dalf Dec 28, 2019
@dalf
dalf approved these changes Dec 28, 2019
Copy link
Collaborator

dalf left a comment

It's all good, except:

  • the column {{mod.suspend_end_time}} to remove (in engines.rst)
  • the href links to remove in arch_public.dot

Anyway I don't think the purpose of this PR is to rewrite all the documentation in one shot, so let's go.
Thank you !

docs/admin/engines.rst Show resolved Hide resolved
docs/admin/arch_public.dot Show resolved Hide resolved
docs/dev/makefile.rst Show resolved Hide resolved
requirements-dev.txt Show resolved Hide resolved
@return42 return42 merged commit f6d66c0 into asciimoo:master Dec 28, 2019
1 check passed
1 check passed
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@return42 return42 removed request for asciimoo, kvch and Pofilo Dec 28, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.