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

Split up documentation #7773

Merged
merged 1 commit into from Mar 27, 2021
Merged

Split up documentation #7773

merged 1 commit into from Mar 27, 2021

Conversation

faho
Copy link
Member

@faho faho commented Mar 3, 2021

This breaks apart the massive "index" document into

  1. An "index" document that explains how to install and set up fish
    and links to the other documents
  2. A "fish-language" document that describes the syntax and semantics
    of the language
  3. A "fish-interactive" document that describes how to use fish
    interactively

No change to the content has been made, only the parts have been moved
from index and some of the formatting (links and header levels) were
fixed.

See #7348.


I would like to have this merged sooner rather than later because most changes to the docs will break it.

Note that this is the first step, in particular we'd have to check all the content still works in context and there is still some random stuff left in index.

We might even want to make a table listing all the other documents.

@faho faho added enhancement docs An issue/PR that touches or should touch the docs labels Mar 3, 2021
@faho faho added this to the fish 3.3.0 milestone Mar 3, 2021
@faho
Copy link
Member Author

faho commented Mar 3, 2021

(also this leaves a bunch of random things in index because I'm not sure where to put them yet)

Copy link
Contributor

@charego charego left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work. I went through to check for broken links and found a few.

Help
----

Fish has an extensive help system. Use the :ref:`help <cmd-help>` command to obtain help on a specific subject or command. For instance, writing ``help syntax`` displays the `syntax section <#syntax>`_ of this documentation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The syntax link is broken for me (goes to interactive.html#syntax).

Also help syntax doesn't work (goes to index.html#syntax).


When the cursor is over a parenthesis or a quote, fish also highlights its matching quote or parenthesis.

To customize the syntax highlighting, you can set the environment variables listed in the `Variables for changing highlighting colors <#variables-color>`__ section.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another broken link.

doc_src/language.rst Show resolved Hide resolved
@faho
Copy link
Member Author

faho commented Mar 8, 2021

I would like to have this merged sooner rather than later because most changes to the docs will break it.

Alright, you know what? That's wrong. I can recreate this whenever needed, I should just fix up the references before (basically the

`thing`_

reference style is broken unless pointing to a full URL, if we had a sphinx linter I'd make it mark that)

- :ref:`dirs <cmd-dirs>` prints the stack
- :ref:`pushd <cmd-pushd>` adds a directory on top of the stack and makes it the current working directory
- :ref:`popd <cmd-popd>` removes the directory on top of the stack and changes the current working directory

.. _initialization:

Initialization files
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This means that after "installation and Start" we have sections

  • Initialization files
  • Future feature flags
  • Event handlers
  • Debugging fish scripts

which are mostly for advanced users. Previously, we had some light introduction, showcasing how to use man and so on.

I know that this is supposed to be reference documentation, not a tutorial (we have one), but maybe make the main page minimal, and move the details somewhere else.

maybe

  • Initialization files -> language
  • Future feature flags -> language
  • Event handlers -> interactive (?)
  • Debugging fish scripts -> interactive/language

Then the "Other help pages" can probably be weeded out a bit, since we mention most sections already.

@ridiculousfish
Copy link
Member

This is already a big improvement! LGTM

This breaks apart the massive "index" document into

1. An "index" document that explains how to install and set up fish
and links to the other documents
2. A "fish-language" document that describes the syntax and semantics
of the language
3. A "fish-interactive" document that describes how to use fish
interactively

No change to the content has been made, only the parts have been moved
from index and some of the formatting (links and header levels) were
fixed.

See fish-shell#7348.
@faho faho merged commit 93eaa61 into fish-shell:master Mar 27, 2021
@faho
Copy link
Member Author

faho commented Mar 27, 2021

Alright, merged now, any other improvement can be done later.

@faho faho deleted the break-up-index branch July 29, 2021 15:57
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 1, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
docs An issue/PR that touches or should touch the docs enhancement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants