Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ jobs:
run: pip install -r requirements.txt

- name: Build pages

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Please add Build pages and run linter

run: make html
run: make check

- name: Deploy to build branch
uses: peaceiris/actions-gh-pages@v3.9.3
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/preview.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ jobs:
run: pip install -r requirements.txt

- name: Build pages

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Please add Build pages and run linter

run: make html
run: make check

- name: Set PR preview path ENVVAR
run: |
Expand Down
8 changes: 8 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,20 @@ SPHINXBUILD ?= sphinx-build
SOURCEDIR = src
BUILDDIR = _build

.PHONY: html fast check linkcheck clean

html: Makefile
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(file) -v

fast: Makefile
@FASTBUILD="yes" $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(file) -v

check: Makefile
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" -E -a -n -W --keep-going $(SPHINXOPTS)

linkcheck: Makefile
@$(SPHINXBUILD) -M linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

clean: Makefile
@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
rmdir "$(BUILDDIR)" || :
16 changes: 13 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ used as well.

[reStructuredText]: https://docutils.sourceforge.io/rst.html
[Sphinx]: https://www.sphinx-doc.org
[MyST]: https://mystmd.org/
[MyST]: https://myst-parser.readthedocs.io/

## Install Python dependencies

Expand Down Expand Up @@ -36,6 +36,16 @@ linked to each other:
(.venv) $ make clean && make html
```

Before submitting a change, run the same strict build used by CI:

```console
(.venv) $ make check
```

This rebuilds every page, enables nitpicky reference checking, and fails on
Sphinx warnings. To check external links as well, run `make linkcheck`;
this requires network access and may report unavailable third-party sites.

## View it
```console
$ firefox _build/html/index.html
Expand All @@ -50,9 +60,9 @@ You do not need to be in virtual environment to see the build result.
add a page to the ToC tree, either include it in `toctree` directive in an
existing document or add it to the top level navigation at the end of the [index]
document.
3. Build the documentation with `make html` and navigate to your page to check
3. Build the documentation with `make check` and navigate to your page to check
that everything is displayed as intended.
4. Open a Pull Request against this repository with your change.

[src]: src
[contents]: src/index.rst
[index]: src/index.rst
21 changes: 9 additions & 12 deletions src/Contribute.rst
Original file line number Diff line number Diff line change
Expand Up @@ -87,17 +87,16 @@ Development
Build and Run
^^^^^^^^^^^^^

See the dedicated `FreeIPA Build Guide <https://www.freeipa.org/page/Build>`__
See the dedicated :doc:`FreeIPA Build Guide </page/Build>`

Contribute code
^^^^^^^^^^^^^^^

- `Contribute code <https://www.freeipa.org/page/Contribute/Code>`__ by
- :doc:`Contribute code </page/Contribute/Code>` by
submitting bug fixes or new features. Help us make FreeIPA great!
- Write a new plugin with a new functionality for FreeIPA and tell us!
Maybe your plugin will make its way to the FreeIPA main project (see
`general
considerations <https://www.freeipa.org/page/General_considerations>`__
:doc:`general considerations </page/General_considerations>`
that plugin developers should keep in mind).

Translate
Expand Down Expand Up @@ -134,28 +133,26 @@ Help Us Test

- Help us test and verify the project by simply using it in your
environment.
- `Testing page <https://www.freeipa.org/page/Testing>`__ is good start
- :doc:`Testing page </page/Testing>` is good start
point and contains the information about execution of existing test
suites.

Contribute Tests
^^^^^^^^^^^^^^^^

- `Contribute tests <https://www.freeipa.org/page/Contribute/Tests>`__
- :doc:`Contribute tests </page/Contribute/Tests>`
by creating test plans or writing new automatized tests that can be
run in `FreeIPA integration
testing <https://www.freeipa.org/page/V3/Integration_testing>`__
run in :doc:`FreeIPA integration testing </page/V3/Integration_testing>`

Documentation
~~~~~~~~~~~~~

Contribute documentation
^^^^^^^^^^^^^^^^^^^^^^^^

- `Help with
documenting <https://www.freeipa.org/page/Contribute/Documentation>`__
- :doc:`Help with documenting </page/Contribute/Documentation>`
new features or adding more information
- `Write a How To <https://www.freeipa.org/page/HowTos>`__ article
- :doc:`Write a How To </page/HowTos>` article
about integrating FreeIPA with other projects
- Do not hesitate to ask on IRC or our mailing lists - see section
`#Communication <https://www.freeipa.org/page/Contribute#Communication>`__.
`Communication <#communication>`__.
13 changes: 6 additions & 7 deletions src/Downloads.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ FreeIPA versions:
Releases in Container
~~~~~~~~~~~~~~~~~~~~~

As described in `Docker <https://www.freeipa.org/page/Docker>`__ page,
As described in :doc:`Docker </page/Docker>`,
the team also maintains PoC container release of FreeIPA:

- `FreeIPA Server on Docker
Expand All @@ -45,23 +45,22 @@ build of FreeIPA, in a nightly repo:
Sources
~~~~~~~

If you want to `build <https://www.freeipa.org/page/Build>`__ FreeIPA
If you want to :doc:`build </page/Build>` FreeIPA
yourself, you can check the sources stored on the project Codeberg:

- `Latest Released Sources <https://codeberg.org/freeipa/freeipa/releases>`__
- `Steps on verifying the
release <https://www.freeipa.org/page/Verify_Release_Signature>`__
- :doc:`Steps on verifying the release </page/Verify_Release_Signature>`

Upgrading FreeIPA
-----------------

Upgrade instructions are available on
`Upgrade <https://www.freeipa.org/page/Upgrade>`__ page.
:doc:`Upgrade </page/Upgrade>` page.

Installing and Using FreeIPA
----------------------------

See `Documentation <https://www.freeipa.org/page/Documentation>`__ or
`Quick Start Guide <https://www.freeipa.org/page/Quick_Start_Guide>`__
See :doc:`Documentation </page/Documentation>` or
:doc:`Quick Start Guide </page/Quick_Start_Guide>`
for further information about what you can do with your new and shiny
FreeIPA server!
14 changes: 1 addition & 13 deletions src/_templates/custom_nav.html
Original file line number Diff line number Diff line change
@@ -1,13 +1 @@
<div class="sidebar-primary-item">
<nav class="bd-links" id="bd-docs-nav" aria-label="Main">
<div class="bd-toc-item navbar-nav active">
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="/About.html">About</a></li>
<li class="toctree-l1"><a class="reference internal" href="/Contribute.html">Contribute</a></li>
<li class="toctree-l1"><a class="reference internal" href="/page/Documentation.html">Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="/page/Troubleshooting.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="/Downloads.html">Downloads</a></li>
</ul>
</div>
</nav>
</div>
{% include "sbt-sidebar-nav.html" %}
6 changes: 3 additions & 3 deletions src/_templates/logo.html
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
<a class="navbar-brand logo" href="/">
<img src="https://raw.githubusercontent.com/freeipa/freeipa.github.io/main/src/_static/freeipa-logo-small.png" class="logo__image" alt="Logo image" />
</a>
<a class="navbar-brand logo" href="{{ pathto(root_doc) }}">
<img src="{{ pathto('_static/freeipa-logo-small.png', 1) }}" class="logo__image" alt="FreeIPA home" />
</a>
11 changes: 8 additions & 3 deletions src/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,13 @@
html_theme = "sphinx_book_theme"
# html_theme_path = ["themes"]

html_sidebars = {
"**": ["logo.html", "search-button-field.html", "custom_nav.html"]
html_theme_options = {
"repository_url": "https://github.com/freeipa/freeipa.github.io",
"repository_branch": "main",
"path_to_docs": "src",
"use_repository_button": True,
"use_edit_page_button": True,
"show_navbar_depth": 1,
}

# Add any paths that contain custom static files (such as style sheets) here,
Expand All @@ -58,4 +63,4 @@

html_static_path = ["_static"]
html_logo = "_static/freeipa-logo-small.png"
html_favicon = '_static/favicon.png'
html_favicon = '_static/favicon.png'
77 changes: 40 additions & 37 deletions src/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,26 +4,26 @@ FreeIPA - Identity, Policy, Audit
Identity
--------

Manage Linux users and `client hosts <https://www.freeipa.org/page/Client>`__ in your realm from `one
central location <https://www.freeipa.org/page/Directory_Server>`__ with CLI, `Web UI <https://www.freeipa.org/page/Web_UI>`__ or
RPC access. Enable `Single Sign On <https://www.freeipa.org/page/Kerberos>`__ authentication for all
Manage Linux users and :doc:`client hosts </page/Client>` in your :term:`realm` from
:doc:`one central location </page/Directory_Server>` with CLI, :doc:`Web UI </page/Web_UI>` or
RPC access. Enable :doc:`Single Sign On </page/Kerberos>` authentication for all
your systems, services and applications.

Policy
------

Define `Kerberos <https://www.freeipa.org/page/Kerberos>`__ authentication and authorization policies
for your identities. Control services like `DNS <https://www.freeipa.org/page/DNS>`__, SUDO, SELinux
Define :doc:`Kerberos </page/Kerberos>` authentication and authorization policies
for your identities. Control services like :doc:`DNS </page/DNS>`, SUDO, SELinux
or autofs.

Trusts
------

Create mutual `trust <https://www.freeipa.org/page/Trusts>`__ with other Identity Management systems
like `Microsoft Active Directory <https://www.freeipa.org/page/Active_Directory_trust_setup>`__.
Create mutual :doc:`trust </page/Trusts>` with other Identity Management systems
like :doc:`Microsoft Active Directory </page/Active_Directory_trust_setup>`.

`About FreeIPA <https://www.freeipa.org/page/About>`__ •\ `Roadmap <https://www.freeipa.org/page/Roadmap>`__ • `FreeIPA
Leaflet <https://www.freeipa.org/page/Leaflet>`__ • `FreeIPA public demo <https://www.freeipa.org/page/Demo>`__ •
:doc:`About FreeIPA </About>` • :doc:`Roadmap </page/Roadmap>` •
:doc:`FreeIPA Leaflet </page/Leaflet>` • :doc:`FreeIPA public demo </page/Demo>` •
`Blogs/RSS <http://planet.freeipa.org>`__


Expand All @@ -49,19 +49,18 @@ Main features
Releases
--------

.. toctree::
:titlesonly:

/release-notes/4-13-5.rst
/release-notes/4-13-4.rst
/release-notes/4-13-3.rst
/release-notes/4-13-2.rst
/release-notes/4-13-1.rst
/release-notes/4-13-0.rst
/release-notes/4-12-5.rst
/release-notes/4-12-4.rst
/release-notes/4-12-3.rst
/release-notes/4-12-2.rst
- :doc:`/release-notes/4-13-5`
- :doc:`/release-notes/4-13-4`
- :doc:`/release-notes/4-13-3`
- :doc:`/release-notes/4-13-2`
- :doc:`/release-notes/4-13-1`
- :doc:`/release-notes/4-13-0`
- :doc:`/release-notes/4-12-5`
- :doc:`/release-notes/4-12-4`
- :doc:`/release-notes/4-12-3`
- :doc:`/release-notes/4-12-2`

See :doc:`/release-notes/index` for all release announcements.

Getting involved
----------------
Expand All @@ -70,35 +69,39 @@ Whether you'd like to contribute to discussion, to code, or simply test
it out, FreeIPA needs your help!

- To contribute to the development of FreeIPA go to
`Contribute <https://www.freeipa.org/page/Contribute>`__ and subscribe to
:doc:`Contribute </Contribute>` and subscribe to
`freeipa-devel <https://lists.fedoraproject.org/archives/list/freeipa-devel@lists.fedorahosted.org/>`__
- To share deployment experience with FreeIPA and ask "how to"
questions subscribe to
`freeipa-users <https://lists.fedoraproject.org/archives/list/freeipa-users@lists.fedorahosted.org/>`__
- To file a bug, RFE or to see where you can help, please see
https://www.freeipa.org/page/Contribute#Reporting_bugs_or_Features
- For security-related communication, please use
https://www.freeipa.org/page/Contribute#Security_Bugs_and_Flaws
- To file a bug, RFE or to see where you can help, please see :doc:`/Contribute`.
- For security-related communication, please use the security contact in
:doc:`/Contribute`.
- Contributions are always welcome!

`Learn more <https://www.freeipa.org/page/Contribute>`__
:doc:`Learn more </Contribute>`

Public Demo
-----------

People eager to try the looks and feel of the most recent FreeIPA, can
visit our `public FreeIPA instance <https://www.freeipa.org/page/Demo>`__! It is great for
visit our :doc:`public FreeIPA instance </page/Demo>`! It is great for

- Testing changes in the most recent CLI/Web UI/API
- Testing `client <https://www.freeipa.org/page/Client>`__ enrollment
- Testing `web applications <https://www.freeipa.org/page/Web_App_Authentication>`__ with
`LDAP <https://www.freeipa.org/page/Directory_Server>`__ / `Kerberos <https://www.freeipa.org/page/Kerberos>`__ authentication
- Testing :doc:`client </page/Client>` enrollment
- Testing :doc:`web applications </page/Web_App_Authentication>` with
:doc:`LDAP </page/Directory_Server>` / :doc:`Kerberos </page/Kerberos>` authentication

Read more on the page `Demo <https://www.freeipa.org/page/Demo>`__.
Read more on the page :doc:`Demo </page/Demo>`.

.. toctree::
:hidden:

About.md
Contribute.md
Downloads.md
:maxdepth: 2

/About
/page/Documentation
/page/Troubleshooting
/glossary
/Downloads
/Contribute
/release-notes/index
Loading
Loading