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

Move away the documentation from the Wiki #1785

Open
dalf opened this issue Dec 22, 2019 · 7 comments
Open

Move away the documentation from the Wiki #1785

dalf opened this issue Dec 22, 2019 · 7 comments
Labels
doc

Comments

@dalf
Copy link
Collaborator

@dalf dalf commented Dec 22, 2019

To do after #1776 is merged : see #1776 (comment)

Most of the wiki content should be moved away 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.

@dalf dalf added the doc label Dec 22, 2019
@return42

This comment has been minimized.

Copy link
Collaborator

@return42 return42 commented Dec 24, 2019

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

I have seen such a "one tab per distrubution" sphinx-theme (or directive?) .. can't remember what and where .. do you have a link, pointing in the right direction / thanks!

@dalf

This comment has been minimized.

Copy link
Collaborator Author

@dalf dalf commented Dec 25, 2019

return42 added a commit to return42/searx that referenced this issue Dec 26, 2019
See issue asciimoo#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>
@return42

This comment has been minimized.

Copy link
Collaborator

@return42 return42 commented Dec 26, 2019

I'm not used to sphinx.

Ups, sorry I thought you fire your preferences from the hip. Was not my aim to instruct you to do a research. Anyway, you brought up what is needed.

All require JS.

Pure CSS has its charm , but it is also hard to maintain or extend. Since JS is already needed by Sphinx (search index), I do not have problems using JS .. I have seen very rare pure CSS Sphinx themes.

column tabs, column content, toggle headers could be useful.

From the JS solutions I chose sphinx-tabs. From my personal view: it follows more the (old) unix philosophy do one thing and do it this well. sphinx-tabs includes Sphinx UI, on the other side, sphinxcontrib-contentui is more handmade and needs less resources. Both have pros and cons .. at least, sphinx-tabs are group able, which seems to fits more to our needs.

Here is a link shows the usage of tabbed views (don't bookmark): https://return42.github.io/searx/dev/reST.html#tabbed-views

return42 added a commit to return42/searx that referenced this issue Dec 30, 2019
Move wiki entry https://github.com/asciimoo/searx/wiki/settings.yml
into admin section of the docs (asciimoo#1785).

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
return42 added a commit to return42/searx that referenced this issue Jan 4, 2020
Move wiki entry https://github.com/asciimoo/searx/wiki/Searx-instances
into user section of the docs (asciimoo#1785).

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

This comment has been minimized.

Copy link
Collaborator

@return42 return42 commented Jan 4, 2020

FYI: I add the Searx-instances wiki to the docs #1791 :

Udate: job done, see https://asciimoo.github.io/searx/user/public_instances.html

return42 added a commit to return42/searx that referenced this issue Jan 4, 2020
Move wiki entry https://github.com/asciimoo/searx/wiki/Searx-instances
into user section of the docs (asciimoo#1785).

links has been ported from markdown to reST by::

      regexpr:        \[([^\]]*)\]\(([^)]*)\)
      substitution:  `\1 <\2>`__

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

This comment has been minimized.

Copy link
Contributor

@unixfox unixfox commented Jan 7, 2020

For the whole documentation for both case.

Do we really need "github" corners? .. we have "Project Links" on top of the left navigation bar and the link to the "Source" is the topmost .. compare: asciimoo.github.io/searx

Not everyone is used to GitHub, if there is a button that leads to the ability to directly add content to the page it's way easier than going to the source code then finding where the file of the page is (because currently it's explained nowhere how to edit the documentation) and finally edit the file.

One thing that creeped me a bit when moving the wiki to the documentation is the ease of editing pages, I don't want to see an amount of contributors reduced because we moved to a reST documentation. The wiki was really easy to edit, the documentation should follow the same simplicity.

@return42

This comment has been minimized.

Copy link
Collaborator

@return42 return42 commented Jan 7, 2020

One thing that creeped me a bit when moving the wiki to the documentation is the ease of editing pages, I don't want to see an amount of contributors reduced because we moved to a reST documentation.

I can understand, that is an argument. On the other side I am not a real fan of to much tooling other than a simple git command line. I also see some drawbacks: Our contributors need a github account, this will lock out other good programmers who do not want to have a github account / most CI quality tooling needs to commit first your mistakes ...

I personally prefer less bindings as possible. but this is not my decision, it is the decision of the maintainer .. so I play the ball to @asciimoo ...

@asciimoo

This comment has been minimized.

Copy link
Owner

@asciimoo asciimoo commented Jan 7, 2020

Our contributors need a github account, this will lock out other good programmers who do not want to have a github account / most CI quality tooling needs to commit first your mistakes ...

I accept patches in email.

I personally prefer less bindings as possible. but this is not my decision, it is the decision of the maintainer .. so I play the ball to @asciimoo ...

I agree

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.